@btst/stack 2.1.0 → 2.3.0

package/dist/shared/stack.snB1EDP7.d.cts

@@ -0,0 +1,419 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
+import { createApiClient } from '@btst/stack/plugins/client';
+import { P as Post, T as Tag, c as createPostSchema, u as updatePostSchema, S as SerializedPost, a as SerializedTag } from './stack.CBON0dWL.cjs';
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import * as better_call from 'better-call';
+import { Adapter } from '@btst/db';
+import { z } from 'zod';
+
+/**
+ * Parameters for filtering/paginating posts.
+ * Mirrors the shape of the list API query schema.
+ */
+interface PostListParams {
+    slug?: string;
+    tagSlug?: string;
+    offset?: number;
+    limit?: number;
+    query?: string;
+    published?: boolean;
+}
+/**
+ * Paginated result returned by {@link getAllPosts}.
+ */
+interface PostListResult {
+    items: Array<Post & {
+        tags: Tag[];
+    }>;
+    total: number;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Retrieve all posts matching optional filter criteria.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks (e.g. `onBeforeListPosts`) are NOT
+ * called. The caller is responsible for any access-control checks before
+ * invoking this function.
+ *
+ * @param adapter - The database adapter
+ * @param params - Optional filter/pagination parameters (same shape as the list API query)
+ */
+declare function getAllPosts(adapter: Adapter, params?: PostListParams): Promise<PostListResult>;
+/**
+ * Retrieve a single post by its slug, including associated tags.
+ * Returns null if no post is 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 slug - The post slug
+ */
+declare function getPostBySlug(adapter: Adapter, slug: string): Promise<(Post & {
+    tags: Tag[];
+}) | null>;
+/**
+ * Retrieve all tags, sorted alphabetically by name.
+ * 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
+ */
+declare function getAllTags(adapter: Adapter): Promise<Tag[]>;
+
+/**
+ * Route keys for the blog plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+type BlogRouteKey = "posts" | "drafts" | "post" | "tag" | "newPost" | "editPost";
+/**
+ * Overloaded signature for `prefetchForRoute`.
+ * TypeScript enforces the correct params for each routeKey at call sites.
+ */
+interface BlogPrefetchForRoute {
+    (key: "posts" | "drafts" | "newPost", qc: QueryClient): Promise<void>;
+    (key: "post" | "editPost", qc: QueryClient, params: {
+        slug: string;
+    }): Promise<void>;
+    (key: "tag", qc: QueryClient, params: {
+        tagSlug: string;
+    }): Promise<void>;
+}
+declare const PostListQuerySchema: z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    tagSlug: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    query: z.ZodOptional<z.ZodString>;
+    published: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean | undefined, string | undefined>>;
+}, z.core.$strip>;
+declare const NextPreviousPostsQuerySchema: z.ZodObject<{
+    date: z.ZodCoercedDate<unknown>;
+}, z.core.$strip>;
+/**
+ * Context passed to blog API hooks
+ */
+interface BlogApiContext<TBody = any, TParams = any, TQuery = any> {
+    body?: TBody;
+    params?: TParams;
+    query?: TQuery;
+    request?: Request;
+    headers?: Headers;
+    [key: string]: any;
+}
+/**
+ * Configuration hooks for blog backend plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface BlogBackendHooks {
+    /**
+     * Called before listing posts. Return false to deny access.
+     * @param filter - Query parameters for filtering posts
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeListPosts?: (filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before creating a post. Return false to deny access.
+     * @param data - Post data being created
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeCreatePost?: (data: z.infer<typeof createPostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a post. Return false to deny access.
+     * @param postId - ID of the post being updated
+     * @param data - Updated post data
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeUpdatePost?: (postId: string, data: z.infer<typeof updatePostSchema>, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a post. Return false to deny access.
+     * @param postId - ID of the post being deleted
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeDeletePost?: (postId: string, context: BlogApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after posts are read successfully
+     * @param posts - The list of posts returned by the query
+     * @param filter - Query parameters used for filtering
+     * @param context - Request context
+     */
+    onPostsRead?: (posts: Array<Post & {
+        tags: Tag[];
+    }>, filter: z.infer<typeof PostListQuerySchema>, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is created successfully
+     * @param post - The created post
+     * @param context - Request context
+     */
+    onPostCreated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is updated successfully
+     * @param post - The updated post
+     * @param context - Request context
+     */
+    onPostUpdated?: (post: Post, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called after a post is deleted successfully
+     * @param postId - ID of the deleted post
+     * @param context - Request context
+     */
+    onPostDeleted?: (postId: string, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when listing posts fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onListPostsError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when creating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onCreatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when updating a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onUpdatePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+    /**
+     * Called when deleting a post fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onDeletePostError?: (error: Error, context: BlogApiContext) => Promise<void> | void;
+}
+/**
+ * Blog backend plugin
+ * Provides API endpoints for managing blog posts
+ * Uses better-db adapter for database operations
+ *
+ * @param hooks - Optional configuration hooks for customizing plugin behavior
+ */
+declare const blogBackendPlugin: (hooks?: BlogBackendHooks) => _btst_stack_plugins_api.BackendPlugin<{
+    readonly listPosts: better_call.StrictEndpoint<"/posts", {
+        method: "GET";
+        query: z.ZodObject<{
+            slug: z.ZodOptional<z.ZodString>;
+            tagSlug: z.ZodOptional<z.ZodString>;
+            offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+            limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+            query: z.ZodOptional<z.ZodString>;
+            published: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<boolean | undefined, string | undefined>>;
+        }, z.core.$strip>;
+    }, PostListResult>;
+    readonly createPost: better_call.StrictEndpoint<"/posts", {
+        method: "POST";
+        body: 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>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            title: z.ZodString;
+            content: z.ZodString;
+            excerpt: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+            published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        }, z.core.$strip>;
+    }, Post>;
+    readonly updatePost: better_call.StrictEndpoint<"/posts/:id", {
+        method: "PUT";
+        body: z.ZodObject<{
+            publishedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            createdAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            updatedAt: z.ZodOptional<z.ZodCoercedDate<unknown>>;
+            title: z.ZodString;
+            content: z.ZodString;
+            excerpt: z.ZodString;
+            image: z.ZodOptional<z.ZodString>;
+            published: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+            slug: z.ZodString;
+            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>]>>>>;
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, Post>;
+    readonly deletePost: better_call.StrictEndpoint<"/posts/:id", {
+        method: "DELETE";
+    }, {
+        success: boolean;
+    }>;
+    readonly getNextPreviousPosts: better_call.StrictEndpoint<"/posts/next-previous", {
+        method: "GET";
+        query: z.ZodObject<{
+            date: z.ZodCoercedDate<unknown>;
+        }, z.core.$strip>;
+    }, {
+        previous: {
+            tags: Tag[];
+            id: string;
+            authorId?: string;
+            defaultLocale?: string;
+            slug: string;
+            title: string;
+            content: string;
+            excerpt: string;
+            image?: string;
+            published: boolean;
+            status?: "DRAFT" | "PUBLISHED";
+            publishedAt?: Date;
+            createdAt: Date;
+            updatedAt: Date;
+        } | null;
+        next: {
+            tags: Tag[];
+            id: string;
+            authorId?: string;
+            defaultLocale?: string;
+            slug: string;
+            title: string;
+            content: string;
+            excerpt: string;
+            image?: string;
+            published: boolean;
+            status?: "DRAFT" | "PUBLISHED";
+            publishedAt?: Date;
+            createdAt: Date;
+            updatedAt: Date;
+        } | null;
+    }>;
+    readonly listTags: better_call.StrictEndpoint<"/tags", {
+        method: "GET";
+    }, Tag[]>;
+}, {
+    getAllPosts: (params?: Parameters<typeof getAllPosts>[1]) => Promise<PostListResult>;
+    getPostBySlug: (slug: string) => Promise<(Post & {
+        tags: Tag[];
+    }) | null>;
+    getAllTags: () => Promise<Tag[]>;
+    prefetchForRoute: BlogPrefetchForRoute;
+}>;
+type BlogApiRouter = ReturnType<ReturnType<typeof blogBackendPlugin>["routes"]>;
+
+/**
+ * Internal query key constants for the blog plugin.
+ * Shared between query-keys.ts (HTTP path) and prefetchForRoute (DB path)
+ * to prevent key drift between SSR loaders and SSG prefetching.
+ */
+interface PostsListDiscriminator {
+    query: string | undefined;
+    limit: number;
+    published: boolean;
+    tagSlug: string | undefined;
+}
+/** Full query key builders — use these with queryClient.setQueryData() */
+declare const BLOG_QUERY_KEYS: {
+    postsList: (params: {
+        published: boolean;
+        limit?: number;
+        tagSlug?: string;
+    }) => readonly ["posts", "list", PostsListDiscriminator];
+    postDetail: (slug: string) => readonly ["posts", "detail", string];
+    tagsList: () => readonly ["tags", "list", "tags"];
+};
+
+interface PostsListParams {
+    query?: string;
+    limit?: number;
+    published?: boolean;
+    tagSlug?: string;
+}
+declare function createBlogQueryKeys(client: ReturnType<typeof createApiClient<BlogApiRouter>>, headers?: HeadersInit): {
+    posts: {
+        _def: readonly ["posts"];
+    } & {
+        list: ((params?: PostsListParams | undefined) => Omit<Omit<{
+            queryKey: readonly ["posts", "list", PostsListDiscriminator];
+            queryFn: _tanstack_react_query.QueryFunction<unknown, readonly ["posts", "list", PostsListDiscriminator]>;
+        }, "queryFn"> & {
+            _def: readonly ["posts", "list"];
+        }, "_def">) & {
+            _def: readonly ["posts", "list"];
+        };
+        detail: ((slug: string) => Omit<{
+            queryKey: readonly ["posts", "detail", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedPost | null, readonly ["posts", "detail", string]>;
+        } & {
+            _def: readonly ["posts", "detail"];
+        }, "_def">) & {
+            _def: readonly ["posts", "detail"];
+        };
+        nextPrevious: ((date: string | Date) => Omit<{
+            queryKey: readonly ["posts", "nextPrevious", string, string | Date];
+            queryFn: _tanstack_react_query.QueryFunction<{
+                previous: SerializedPost | null;
+                next: SerializedPost | null;
+            }, readonly ["posts", "nextPrevious", string, string | Date]>;
+        } & {
+            _def: readonly ["posts", "nextPrevious"];
+        }, "_def">) & {
+            _def: readonly ["posts", "nextPrevious"];
+        };
+        recent: ((params?: {
+            limit?: number;
+            excludeSlug?: string;
+        } | undefined) => Omit<{
+            queryKey: readonly ["posts", "recent", string, {
+                limit?: number;
+                excludeSlug?: string;
+            } | undefined];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedPost[], readonly ["posts", "recent", string, {
+                limit?: number;
+                excludeSlug?: string;
+            } | undefined]>;
+        } & {
+            _def: readonly ["posts", "recent"];
+        }, "_def">) & {
+            _def: readonly ["posts", "recent"];
+        };
+    };
+    drafts: {
+        _def: readonly ["drafts"];
+    } & {
+        list: ((params?: PostsListParams | undefined) => Omit<Omit<{
+            queryKey: readonly ["drafts", "list", {
+                limit?: number | undefined;
+            }];
+            queryFn: _tanstack_react_query.QueryFunction<unknown, readonly ["drafts", "list", {
+                limit?: number | undefined;
+            }]>;
+        }, "queryFn"> & {
+            _def: readonly ["drafts", "list"];
+        }, "_def">) & {
+            _def: readonly ["drafts", "list"];
+        };
+    };
+    tags: {
+        _def: readonly ["tags"];
+    } & {
+        list: (() => Omit<{
+            queryKey: readonly ["tags", "list", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedTag[], readonly ["tags", "list", string]>;
+        } & {
+            _def: readonly ["tags", "list"];
+        }, "_def">) & {
+            _def: readonly ["tags", "list"];
+        };
+    };
+};
+
+export { BLOG_QUERY_KEYS as B, NextPreviousPostsQuerySchema as N, getPostBySlug as a, getAllTags as b, createBlogQueryKeys as d, PostListQuerySchema as f, getAllPosts as g, blogBackendPlugin as j };
+export type { PostListParams as P, PostListResult as c, BlogRouteKey as e, BlogApiContext as h, BlogBackendHooks as i, BlogApiRouter as k };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btst/stack",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "A composable, plugin-based library for building full-stack applications.",
   "repository": {
     "type": "git",
@@ -458,7 +458,7 @@
   },
   "peerDependencies": {
     "@ai-sdk/react": ">=2.0.0",
-    "@btst/yar": ">=1.1.0",
+    "@btst/yar": ">=1.2.0",
     "@hookform/resolvers": ">=5.0.0",
     "@radix-ui/react-dialog": ">=1.1.0",
     "@radix-ui/react-label": ">=2.1.0",
@@ -494,7 +494,7 @@
   "devDependencies": {
     "@ai-sdk/react": "^2.0.94",
     "@btst/adapter-memory": "2.0.3",
-    "@btst/yar": "1.1.1",
+    "@btst/yar": "1.2.0",
     "@types/react": "^19.0.0",
     "@types/slug": "^5.0.9",
     "@workspace/ui": "workspace:*",

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";