@btst/stack 2.2.0 → 2.4.0

package/dist/plugins/kanban/query-keys.mjs

@@ -1,4 +1,5 @@
 import { mergeQueryKeys, createQueryKeys } from '@lukemorales/query-key-factory';
+import { boardsListDiscriminator } from '../../packages/stack/src/plugins/kanban/api/query-key-defs.mjs';
 
 function isErrorResponse(response) {
   return typeof response === "object" && response !== null && "error" in response && response.error !== null && response.error !== void 0;
@@ -23,15 +24,7 @@ function createKanbanQueryKeys(client, headers) {
 function createBoardsQueries(client, headers) {
   return createQueryKeys("boards", {
     list: (params) => ({
-      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", {

package/dist/plugins/ui-builder/index.d.cts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { C as ContentTypeConfig } from '../../shared/stack.CXjzTMsb.cjs';
+import { C as ContentTypeConfig } from '../../shared/stack.CVDTkMoO.cjs';
 export { L as LoaderContext, b as PaginatedUIBuilderPages, P as ParsedUIBuilderPage, S as SerializedUIBuilderPage, c as UIBuilderClientHooks, a as UIBuilderPage, U as UIBuilderPageData } from '../../shared/stack.C-WUPMT6.cjs';
 export { C as ComponentLayer, a as ComponentRegistry, R as RegistryEntry, V as Variable } from '../../shared/stack.B-YHz18S.cjs';
 import 'react';

package/dist/plugins/ui-builder/index.d.mts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { C as ContentTypeConfig } from '../../shared/stack.CXjzTMsb.mjs';
+import { C as ContentTypeConfig } from '../../shared/stack.CVDTkMoO.mjs';
 export { L as LoaderContext, b as PaginatedUIBuilderPages, P as ParsedUIBuilderPage, S as SerializedUIBuilderPage, c as UIBuilderClientHooks, a as UIBuilderPage, U as UIBuilderPageData } from '../../shared/stack.6fUOjLs9.mjs';
 export { C as ComponentLayer, a as ComponentRegistry, R as RegistryEntry, V as Variable } from '../../shared/stack.D1DMlJp-.mjs';
 import 'react';

package/dist/plugins/ui-builder/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { C as ContentTypeConfig } from '../../shared/stack.CXjzTMsb.js';
+import { C as ContentTypeConfig } from '../../shared/stack.CVDTkMoO.js';
 export { L as LoaderContext, b as PaginatedUIBuilderPages, P as ParsedUIBuilderPage, S as SerializedUIBuilderPage, c as UIBuilderClientHooks, a as UIBuilderPage, U as UIBuilderPageData } from '../../shared/stack.C-Ptrz8s.js';
 export { C as ComponentLayer, a as ComponentRegistry, R as RegistryEntry, V as Variable } from '../../shared/stack.GygI_T3X.js';
 import 'react';

package/dist/shared/stack.B7ONvlD_.d.mts

@@ -0,0 +1,293 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import * as better_call from 'better-call';
+import { S as SerializedForm, b as SerializedFormSubmissionWithData, F as Form, d as FormSubmission, a as SerializedFormSubmission, e as FormSubmissionWithForm, f as FormBuilderBackendConfig } from './stack.DdI5W6MB.mjs';
+import { z } from 'zod';
+import { Adapter } from '@btst/db';
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * Serialize a Form for SSR/SSG use (convert dates to strings).
+ */
+declare function serializeForm(form: Form): SerializedForm;
+/**
+ * Serialize a FormSubmission for SSR/SSG use (convert dates to strings).
+ */
+declare function serializeFormSubmission(submission: FormSubmission): SerializedFormSubmission;
+/**
+ * Serialize a FormSubmission with parsed data and joined Form.
+ * If `submission.data` is corrupted JSON, `parsedData` is set to `null` rather
+ * than throwing, so one bad row cannot crash the entire list or SSG build.
+ */
+declare function serializeFormSubmissionWithData(submission: FormSubmissionWithForm): SerializedFormSubmissionWithData;
+/**
+ * Retrieve all forms with optional status filter and pagination.
+ * Pure DB function — no hooks, no HTTP context. Safe for SSG and server-side use.
+ *
+ * @remarks **Security:** Authorization hooks (e.g. `onBeforeListForms`) 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
+ */
+declare function getAllForms(adapter: Adapter, params?: {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    items: SerializedForm[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}>;
+/**
+ * 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
+ */
+declare function getFormById(adapter: Adapter, id: string): Promise<SerializedForm | null>;
+/**
+ * Retrieve a single form by its slug.
+ * 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 slug - The form slug
+ */
+declare function getFormBySlug(adapter: Adapter, slug: string): Promise<SerializedForm | null>;
+/**
+ * Retrieve submissions for a form by form ID, with optional pagination.
+ * Returns an empty result if the form does not exist.
+ * Pure DB function — no hooks, no HTTP context. Safe for 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 formId - The form ID
+ * @param params - Optional pagination parameters
+ */
+declare function getFormSubmissions(adapter: Adapter, formId: string, params?: {
+    limit?: number;
+    offset?: number;
+}): Promise<{
+    items: SerializedFormSubmissionWithData[];
+    total: number;
+    limit?: number;
+    offset?: number;
+}>;
+
+/**
+ * Route keys for the Form Builder plugin — matches the keys returned by
+ * `stackClient.router.getRoute(path).routeKey`.
+ */
+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>;
+}
+/**
+ * Form Builder backend plugin
+ * Provides API endpoints for managing forms and form submissions
+ *
+ * @param config - Configuration with optional hooks
+ */
+declare const formBuilderBackendPlugin: (config?: FormBuilderBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
+    listForms: better_call.StrictEndpoint<"/forms", {
+        method: "GET";
+        query: z.ZodObject<{
+            status: z.ZodOptional<z.ZodEnum<{
+                active: "active";
+                inactive: "inactive";
+                archived: "archived";
+            }>>;
+            limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+            offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+        }, z.core.$strip>;
+    }, {
+        items: SerializedForm[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getFormBySlug: better_call.StrictEndpoint<"/forms/:slug", {
+        method: "GET";
+        params: z.ZodObject<{
+            slug: z.ZodString;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    getFormById: better_call.StrictEndpoint<"/forms/id/:id", {
+        method: "GET";
+        params: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    createForm: better_call.StrictEndpoint<"/forms", {
+        method: "POST";
+        body: z.ZodObject<{
+            name: z.ZodString;
+            slug: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            schema: z.ZodString;
+            successMessage: z.ZodOptional<z.ZodString>;
+            redirectUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+            status: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+                active: "active";
+                inactive: "inactive";
+                archived: "archived";
+            }>>>;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    updateForm: better_call.StrictEndpoint<"/forms/:id", {
+        method: "PUT";
+        params: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+        body: z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            slug: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            schema: z.ZodOptional<z.ZodString>;
+            successMessage: z.ZodOptional<z.ZodString>;
+            redirectUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+            status: z.ZodOptional<z.ZodEnum<{
+                active: "active";
+                inactive: "inactive";
+                archived: "archived";
+            }>>;
+        }, z.core.$strip>;
+    }, SerializedForm>;
+    deleteForm: better_call.StrictEndpoint<"/forms/:id", {
+        method: "DELETE";
+        params: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, {
+        success: boolean;
+    }>;
+    submitForm: better_call.StrictEndpoint<"/forms/:slug/submit", {
+        method: "POST";
+        params: z.ZodObject<{
+            slug: z.ZodString;
+        }, z.core.$strip>;
+        body: z.ZodObject<{
+            data: z.ZodObject<{}, z.core.$loose>;
+        }, z.core.$strip>;
+    }, {
+        form: {
+            successMessage: string | undefined;
+            redirectUrl: string | undefined;
+        };
+        submittedAt: string;
+        id: string;
+        data: string;
+        formId: string;
+        submittedBy?: string | undefined;
+        ipAddress?: string | undefined;
+        userAgent?: string | undefined;
+    }>;
+    listSubmissions: better_call.StrictEndpoint<"/forms/:formId/submissions", {
+        method: "GET";
+        params: z.ZodObject<{
+            formId: z.ZodString;
+        }, z.core.$strip>;
+        query: z.ZodObject<{
+            limit: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+            offset: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+        }, z.core.$strip>;
+    }, {
+        items: SerializedFormSubmissionWithData[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getSubmission: better_call.StrictEndpoint<"/forms/:formId/submissions/:subId", {
+        method: "GET";
+        params: z.ZodObject<{
+            formId: z.ZodString;
+            subId: z.ZodString;
+        }, z.core.$strip>;
+    }, SerializedFormSubmissionWithData<Record<string, unknown>>>;
+    deleteSubmission: better_call.StrictEndpoint<"/forms/:formId/submissions/:subId", {
+        method: "DELETE";
+        params: z.ZodObject<{
+            formId: z.ZodString;
+            subId: z.ZodString;
+        }, z.core.$strip>;
+    }, {
+        success: boolean;
+    }>;
+}, {
+    getAllForms: (params?: Parameters<typeof getAllForms>[1]) => Promise<{
+        items: SerializedForm[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    getFormById: (id: string) => Promise<SerializedForm | null>;
+    getFormBySlug: (slug: string) => Promise<SerializedForm | null>;
+    getFormSubmissions: (formId: string, params?: Parameters<typeof getFormSubmissions>[2]) => Promise<{
+        items: SerializedFormSubmissionWithData[];
+        total: number;
+        limit?: number;
+        offset?: number;
+    }>;
+    prefetchForRoute: FormBuilderPrefetchForRoute;
+}>;
+type FormBuilderApiRouter = ReturnType<ReturnType<typeof formBuilderBackendPlugin>["routes"]>;
+
+/**
+ * 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.
+ */
+interface FormsListDiscriminator {
+    status?: "active" | "inactive" | "archived";
+    limit: number;
+    offset: number;
+}
+interface SubmissionsListDiscriminator {
+    formId: string;
+    limit: number;
+    offset: number;
+}
+/** Full query key builders — use these with queryClient.setQueryData() */
+declare 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;
+    }) => readonly ["forms", "list", "list", FormsListDiscriminator];
+    /**
+     * Key for forms.byId(id) query.
+     * Full key: ["forms", "byId", "byId", id]
+     */
+    formById: (id: string) => readonly ["forms", "byId", "byId", string];
+    /**
+     * Key for formSubmissions.list(params) query.
+     * Full key: ["formSubmissions", "list", { formId, limit, offset }]
+     */
+    submissionsList: (params: {
+        formId: string;
+        limit?: number;
+        offset?: number;
+    }) => readonly ["formSubmissions", "list", SubmissionsListDiscriminator];
+};
+
+export { getFormById as c, getFormBySlug as d, getFormSubmissions as e, formBuilderBackendPlugin as f, getAllForms as g, serializeFormSubmission as h, serializeFormSubmissionWithData as i, FORM_QUERY_KEYS as j, serializeForm as s };
+export type { FormBuilderApiRouter as F, SubmissionsListDiscriminator as S, FormsListDiscriminator as a, FormBuilderRouteKey as b };

package/dist/shared/{stack.BeSm90va.d.ts → stack.BEn34wW6.d.ts}

@@ -5,7 +5,7 @@ import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
 import * as better_call from 'better-call';
 import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
-import { LanguageModel, Tool } from 'ai';
+import { Tool, LanguageModel } from 'ai';
 
 /**
  * Context passed to AI Chat API hooks
@@ -67,6 +67,18 @@ interface AiChatBackendHooks {
      * @param context - Request context with headers, etc.
      */
     onBeforeDeleteConversation?: (conversationId: string, context: ChatApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after the structural routeName/allowlist validation, with the list
+     * of tool names that passed. Return a filtered subset to further restrict
+     * which tools the LLM sees, or return [] to suppress all page tools.
+     * Throw an Error to abort the entire chat request with a 403 response.
+     * Not called when no tools passed the structural validation step.
+     *
+     * @param toolNames - Names that passed the routeName allowlist check
+     * @param routeName - routeName claimed by the request (may be undefined)
+     * @param context   - Full request context (headers, body, etc.)
+     */
+    onBeforeToolsActivated?: (toolNames: string[], routeName: string | undefined, context: ChatApiContext) => Promise<string[]> | string[];
     /**
      * Called after a chat message is processed successfully
      * @param conversationId - ID of the conversation
@@ -152,6 +164,23 @@ type AiChatMode = "authenticated" | "public";
 /**
  * Configuration for AI Chat backend plugin
  */
+/**
+ * Extracts only the literal (non-index-signature) keys from a type.
+ * For `Record<string, T>` this resolves to `never`, so collision checks are
+ * skipped when the tools map is typed with a broad string index.
+ */
+type KnownKeys<T> = {
+    [K in keyof T]: string extends K ? never : K;
+}[keyof T];
+/**
+ * Ensures `TClientTools` has no keys that are also literal keys in `TTools`.
+ * Colliding keys are mapped to `never`, which produces a compile-time error
+ * at the point of the duplicate key. When `TTools` uses a string index
+ * signature the check is skipped to avoid false positives.
+ */
+type NoKeyCollision<TTools, TClientTools extends Record<string, Tool>> = KnownKeys<TTools> & keyof TClientTools extends never ? TClientTools : {
+    [K in keyof TClientTools]: K extends KnownKeys<TTools> ? never : TClientTools[K];
+};
 interface AiChatBackendConfig {
     /**
      * The language model to use for chat completions.
@@ -182,6 +211,29 @@ interface AiChatBackendConfig {
      * @see https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling
      */
     tools?: Record<string, Tool>;
+    /**
+     * Enable route-aware page tools.
+     * When true, the server will include tool schemas for client-side page tools
+     * (e.g. fillBlogForm, updatePageLayers) based on the availableTools list
+     * sent with each request.
+     * @default false
+     */
+    enablePageTools?: boolean;
+    /**
+     * Custom client-side tool schemas for non-BTST pages.
+     * Merged with built-in page tool schemas (fillBlogForm, updatePageLayers).
+     * Only included when enablePageTools is true and the tool name appears in
+     * the availableTools list sent with the request.
+     *
+     * @example
+     * clientToolSchemas: {
+     *   addToCart: tool({
+     *     description: "Add current product to cart",
+     *     parameters: z.object({ quantity: z.number().int().min(1) }),
+     *   }),
+     * }
+     */
+    clientToolSchemas?: Record<string, Tool>;
     /**
      * Optional hooks for customizing plugin behavior
      */
@@ -194,7 +246,10 @@ interface AiChatBackendConfig {
  *
  * @param config - Configuration including model, tools, and optional hooks
  */
-declare const aiChatBackendPlugin: (config: AiChatBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
+declare const aiChatBackendPlugin: <TTools extends Record<string, Tool> = Record<never, Tool>, TClientTools extends Record<string, Tool> = Record<never, Tool>>(config: Omit<AiChatBackendConfig, "tools" | "clientToolSchemas"> & {
+    tools?: TTools;
+    clientToolSchemas?: NoKeyCollision<TTools, TClientTools>;
+}) => _btst_stack_plugins_api.BackendPlugin<{
     chat: better_call.StrictEndpoint<"/chat", {
         method: "POST";
         body: zod.ZodObject<{
@@ -223,6 +278,9 @@ declare const aiChatBackendPlugin: (config: AiChatBackendConfig) => _btst_stack_
             }, zod_v4_core.$strip>]>>;
             conversationId: zod.ZodOptional<zod.ZodString>;
             model: zod.ZodOptional<zod.ZodString>;
+            pageContext: zod.ZodOptional<zod.ZodString>;
+            availableTools: zod.ZodOptional<zod.ZodArray<zod.ZodString>>;
+            routeName: zod.ZodOptional<zod.ZodString>;
         }, zod_v4_core.$strip>;
     }, Response>;
     createConversation: better_call.StrictEndpoint<"/chat/conversations", {