@btst/stack 2.1.0 → 2.2.0

package/dist/plugins/route-docs/client/index.d.mts

@@ -2,7 +2,7 @@ import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import * as react from 'react';
 import * as _btst_yar from '@btst/yar';
 import { QueryClient } from '@tanstack/react-query';
-import { a as SitemapEntry, b as ClientStackContext } from '../../../shared/stack.BoA0xkJv.mjs';
+import { a as SitemapEntry, b as ClientStackContext } from '../../../shared/stack.7n9Y_u7N.mjs';
 import '@btst/db';
 import 'better-call';
 

package/dist/plugins/route-docs/client/index.d.ts

@@ -2,7 +2,7 @@ import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
 import * as react from 'react';
 import * as _btst_yar from '@btst/yar';
 import { QueryClient } from '@tanstack/react-query';
-import { a as SitemapEntry, b as ClientStackContext } from '../../../shared/stack.BoA0xkJv.js';
+import { a as SitemapEntry, b as ClientStackContext } from '../../../shared/stack.7n9Y_u7N.js';
 import '@btst/db';
 import 'better-call';
 

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { C as ContentTypeConfig } from '../../shared/stack.BsXokfNh.cjs';
+import { C as ContentTypeConfig } from '../../shared/stack.CXjzTMsb.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.BsXokfNh.mjs';
+import { C as ContentTypeConfig } from '../../shared/stack.CXjzTMsb.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.BsXokfNh.js';
+import { C as ContentTypeConfig } from '../../shared/stack.CXjzTMsb.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.BoA0xkJv.d.cts → stack.7n9Y_u7N.d.cts}

@@ -8,7 +8,7 @@ import { Endpoint, Router } from 'better-call';
  */
 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 */
@@ -33,8 +33,11 @@ interface ClientStackContext<TPlugins extends Record<string, ClientPlugin<any, a
  * 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.
  */
-interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>, TApi extends Record<string, (...args: any[]) => any> = never> {
     name: string;
     /**
      * Create API endpoints for this plugin
@@ -46,6 +49,14 @@ interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string
      */
     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;
 }
 /**
  * Frontend plugin definition
@@ -70,10 +81,21 @@ interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Recor
      */
     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.
+ */
+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
  */
-interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any>> = Record<string, BackendPlugin<any>>> {
+interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any, any>> = Record<string, BackendPlugin<any, any>>> {
     basePath: string;
     dbSchema?: DatabaseDefinition;
     plugins: TPlugins;
@@ -109,18 +131,22 @@ type PluginRoutes<TPlugins extends Record<string, ClientPlugin<any, any>>> = Mer
  * Prefix all backend plugin route keys with the plugin name
  * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
  */
-type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any>>> = UnionToIntersection<{
-    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes> ? {
+type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any, any>>> = UnionToIntersection<{
+    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes, any> ? {
         [RouteKey in keyof TRoutes as `${PluginKey & string}_${RouteKey & string}`]: TRoutes[RouteKey];
     } : never;
 }[keyof TPlugins]> extends infer U ? U extends Record<string, Endpoint> ? U : Record<string, Endpoint> : Record<string, Endpoint>;
 /**
  * Result of creating the backend library
  */
-interface BackendLib<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+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>;
     router: Router;
     dbSchema: DatabaseDefinition;
+    /** The database adapter shared across all plugins */
+    adapter: Adapter;
+    /** Fully-typed server-side getter functions, namespaced per plugin */
+    api: TApis;
 }
 /**
  * Helper type to extract routes from a client plugin
@@ -154,4 +180,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, StackContext as S, SitemapEntry as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, StackContext as S, SitemapEntry as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i, PluginApis as j };

package/dist/shared/{stack.BoA0xkJv.d.mts → stack.7n9Y_u7N.d.mts}

@@ -8,7 +8,7 @@ import { Endpoint, Router } from 'better-call';
  */
 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 */
@@ -33,8 +33,11 @@ interface ClientStackContext<TPlugins extends Record<string, ClientPlugin<any, a
  * 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.
  */
-interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>, TApi extends Record<string, (...args: any[]) => any> = never> {
     name: string;
     /**
      * Create API endpoints for this plugin
@@ -46,6 +49,14 @@ interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string
      */
     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;
 }
 /**
  * Frontend plugin definition
@@ -70,10 +81,21 @@ interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Recor
      */
     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.
+ */
+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
  */
-interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any>> = Record<string, BackendPlugin<any>>> {
+interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any, any>> = Record<string, BackendPlugin<any, any>>> {
     basePath: string;
     dbSchema?: DatabaseDefinition;
     plugins: TPlugins;
@@ -109,18 +131,22 @@ type PluginRoutes<TPlugins extends Record<string, ClientPlugin<any, any>>> = Mer
  * Prefix all backend plugin route keys with the plugin name
  * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
  */
-type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any>>> = UnionToIntersection<{
-    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes> ? {
+type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any, any>>> = UnionToIntersection<{
+    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes, any> ? {
         [RouteKey in keyof TRoutes as `${PluginKey & string}_${RouteKey & string}`]: TRoutes[RouteKey];
     } : never;
 }[keyof TPlugins]> extends infer U ? U extends Record<string, Endpoint> ? U : Record<string, Endpoint> : Record<string, Endpoint>;
 /**
  * Result of creating the backend library
  */
-interface BackendLib<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+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>;
     router: Router;
     dbSchema: DatabaseDefinition;
+    /** The database adapter shared across all plugins */
+    adapter: Adapter;
+    /** Fully-typed server-side getter functions, namespaced per plugin */
+    api: TApis;
 }
 /**
  * Helper type to extract routes from a client plugin
@@ -154,4 +180,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, StackContext as S, SitemapEntry as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, StackContext as S, SitemapEntry as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i, PluginApis as j };

package/dist/shared/{stack.BoA0xkJv.d.ts → stack.7n9Y_u7N.d.ts}

@@ -8,7 +8,7 @@ import { Endpoint, Router } from 'better-call';
  */
 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 */
@@ -33,8 +33,11 @@ interface ClientStackContext<TPlugins extends Record<string, ClientPlugin<any, a
  * 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.
  */
-interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>, TApi extends Record<string, (...args: any[]) => any> = never> {
     name: string;
     /**
      * Create API endpoints for this plugin
@@ -46,6 +49,14 @@ interface BackendPlugin<TRoutes extends Record<string, Endpoint> = Record<string
      */
     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;
 }
 /**
  * Frontend plugin definition
@@ -70,10 +81,21 @@ interface ClientPlugin<TOverrides = Record<string, never>, TRoutes extends Recor
      */
     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.
+ */
+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
  */
-interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any>> = Record<string, BackendPlugin<any>>> {
+interface BackendLibConfig<TPlugins extends Record<string, BackendPlugin<any, any>> = Record<string, BackendPlugin<any, any>>> {
     basePath: string;
     dbSchema?: DatabaseDefinition;
     plugins: TPlugins;
@@ -109,18 +131,22 @@ type PluginRoutes<TPlugins extends Record<string, ClientPlugin<any, any>>> = Mer
  * Prefix all backend plugin route keys with the plugin name
  * Example: { messages: { list: Endpoint } } => { messages_list: Endpoint }
  */
-type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any>>> = UnionToIntersection<{
-    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes> ? {
+type PrefixedPluginRoutes<TPlugins extends Record<string, BackendPlugin<any, any>>> = UnionToIntersection<{
+    [PluginKey in keyof TPlugins]: TPlugins[PluginKey] extends BackendPlugin<infer TRoutes, any> ? {
         [RouteKey in keyof TRoutes as `${PluginKey & string}_${RouteKey & string}`]: TRoutes[RouteKey];
     } : never;
 }[keyof TPlugins]> extends infer U ? U extends Record<string, Endpoint> ? U : Record<string, Endpoint> : Record<string, Endpoint>;
 /**
  * Result of creating the backend library
  */
-interface BackendLib<TRoutes extends Record<string, Endpoint> = Record<string, Endpoint>> {
+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>;
     router: Router;
     dbSchema: DatabaseDefinition;
+    /** The database adapter shared across all plugins */
+    adapter: Adapter;
+    /** Fully-typed server-side getter functions, namespaced per plugin */
+    api: TApis;
 }
 /**
  * Helper type to extract routes from a client plugin
@@ -154,4 +180,4 @@ type SitemapEntry = {
 };
 type Sitemap = Array<SitemapEntry>;
 
-export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, StackContext as S, SitemapEntry as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i };
+export type { BackendPlugin as B, ClientPlugin as C, PluginOverrides as P, StackContext as S, SitemapEntry as a, ClientStackContext as b, Sitemap as c, PluginRoutes as d, ClientLibConfig as e, ClientLib as f, PrefixedPluginRoutes as g, BackendLibConfig as h, BackendLib as i, PluginApis as j };

package/dist/shared/stack.BeSm90va.d.ts

@@ -0,0 +1,289 @@
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { createApiClient } from '@btst/stack/plugins/client';
+import { M as Message, C as Conversation, S as SerializedConversation, a as SerializedMessage } from './stack.Be1QIHEn.js';
+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';
+
+/**
+ * Context passed to AI Chat API hooks
+ */
+interface ChatApiContext<TBody = any, TParams = any, TQuery = any> {
+    body?: TBody;
+    params?: TParams;
+    query?: TQuery;
+    request?: Request;
+    headers?: Headers;
+    [key: string]: any;
+}
+/**
+ * Configuration hooks for AI Chat backend plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface AiChatBackendHooks {
+    /**
+     * Called before processing a chat message. Return false to deny access.
+     * @param messages - Array of messages being sent
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeChat?: (messages: Array<{
+        role: string;
+        content: string;
+    }>, context: ChatApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before listing conversations. Return false to deny access.
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeListConversations?: (context: ChatApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before getting a single conversation. Return false to deny access.
+     * @param conversationId - ID of the conversation being accessed
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeGetConversation?: (conversationId: string, context: ChatApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before creating a conversation. Return false to deny access.
+     * @param data - Conversation data being created
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeCreateConversation?: (data: {
+        id?: string;
+        title?: string;
+    }, context: ChatApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before updating a conversation. Return false to deny access.
+     * @param conversationId - ID of the conversation being updated
+     * @param data - Updated conversation data
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeUpdateConversation?: (conversationId: string, data: {
+        title?: string;
+    }, context: ChatApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called before deleting a conversation. Return false to deny access.
+     * @param conversationId - ID of the conversation being deleted
+     * @param context - Request context with headers, etc.
+     */
+    onBeforeDeleteConversation?: (conversationId: string, context: ChatApiContext) => Promise<boolean> | boolean;
+    /**
+     * Called after a chat message is processed successfully
+     * @param conversationId - ID of the conversation
+     * @param messages - Array of messages in the conversation
+     * @param context - Request context
+     */
+    onAfterChat?: (conversationId: string, messages: Message[], context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called after conversations are read successfully
+     * @param conversations - Array of conversations that were read
+     * @param context - Request context
+     */
+    onConversationsRead?: (conversations: Conversation[], context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called after a single conversation is read successfully
+     * @param conversation - The conversation with messages
+     * @param context - Request context
+     */
+    onConversationRead?: (conversation: Conversation & {
+        messages: Message[];
+    }, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called after a conversation is created successfully
+     * @param conversation - The created conversation
+     * @param context - Request context
+     */
+    onConversationCreated?: (conversation: Conversation, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called after a conversation is updated successfully
+     * @param conversation - The updated conversation
+     * @param context - Request context
+     */
+    onConversationUpdated?: (conversation: Conversation, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called after a conversation is deleted successfully
+     * @param conversationId - ID of the deleted conversation
+     * @param context - Request context
+     */
+    onConversationDeleted?: (conversationId: string, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called when a chat operation fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onChatError?: (error: Error, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called when listing conversations fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onListConversationsError?: (error: Error, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called when getting a conversation fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onGetConversationError?: (error: Error, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called when creating a conversation fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onCreateConversationError?: (error: Error, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called when updating a conversation fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onUpdateConversationError?: (error: Error, context: ChatApiContext) => Promise<void> | void;
+    /**
+     * Called when deleting a conversation fails
+     * @param error - The error that occurred
+     * @param context - Request context
+     */
+    onDeleteConversationError?: (error: Error, context: ChatApiContext) => Promise<void> | void;
+}
+/**
+ * Plugin mode for AI Chat
+ * - 'authenticated': Conversations persisted with userId (default)
+ * - 'public': Stateless chat, no persistence (ideal for public chatbots)
+ */
+type AiChatMode = "authenticated" | "public";
+/**
+ * Configuration for AI Chat backend plugin
+ */
+interface AiChatBackendConfig {
+    /**
+     * The language model to use for chat completions.
+     * Supports any model from AI SDK providers (OpenAI, Anthropic, Google, etc.)
+     */
+    model: LanguageModel;
+    /**
+     * Plugin mode:
+     * - 'authenticated': Conversations persisted with userId (requires getUserId)
+     * - 'public': Stateless chat, no persistence (ideal for public chatbots)
+     * @default 'authenticated'
+     */
+    mode?: AiChatMode;
+    /**
+     * Extract userId from request context (authenticated mode only).
+     * Return null/undefined to deny access in authenticated mode.
+     * This function is called for all conversation operations.
+     * @example (ctx) => ctx.headers?.get('x-user-id')
+     */
+    getUserId?: (context: ChatApiContext) => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Optional system prompt to prepend to all conversations
+     */
+    systemPrompt?: string;
+    /**
+     * Optional tools to make available to the model.
+     * Uses AI SDK v5 tool format.
+     * @see https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling
+     */
+    tools?: Record<string, Tool>;
+    /**
+     * Optional hooks for customizing plugin behavior
+     */
+    hooks?: AiChatBackendHooks;
+}
+/**
+ * AI Chat backend plugin
+ * Provides API endpoints for AI-powered chat with conversation history
+ * Uses AI SDK v5 for model interactions
+ *
+ * @param config - Configuration including model, tools, and optional hooks
+ */
+declare const aiChatBackendPlugin: (config: AiChatBackendConfig) => _btst_stack_plugins_api.BackendPlugin<{
+    chat: better_call.StrictEndpoint<"/chat", {
+        method: "POST";
+        body: zod.ZodObject<{
+            messages: zod.ZodArray<zod.ZodUnion<readonly [zod.ZodObject<{
+                role: zod.ZodEnum<{
+                    system: "system";
+                    user: "user";
+                    assistant: "assistant";
+                    data: "data";
+                }>;
+                content: zod.ZodString;
+                id: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>, zod.ZodObject<{
+                role: zod.ZodEnum<{
+                    system: "system";
+                    user: "user";
+                    assistant: "assistant";
+                    data: "data";
+                }>;
+                parts: zod.ZodArray<zod.ZodObject<{
+                    type: zod.ZodString;
+                    text: zod.ZodOptional<zod.ZodString>;
+                }, zod_v4_core.$loose>>;
+                id: zod.ZodOptional<zod.ZodString>;
+                metadata: zod.ZodOptional<zod.ZodAny>;
+            }, zod_v4_core.$strip>]>>;
+            conversationId: zod.ZodOptional<zod.ZodString>;
+            model: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strip>;
+    }, Response>;
+    createConversation: better_call.StrictEndpoint<"/chat/conversations", {
+        method: "POST";
+        body: zod.ZodObject<{
+            id: zod.ZodOptional<zod.ZodString>;
+            title: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strip>;
+    }, Conversation>;
+    listConversations: better_call.StrictEndpoint<"/chat/conversations", {
+        method: "GET";
+    }, Conversation[]>;
+    getConversation: better_call.StrictEndpoint<"/chat/conversations/:id", {
+        method: "GET";
+    }, Conversation & {
+        messages: Message[];
+    }>;
+    updateConversation: better_call.StrictEndpoint<"/chat/conversations/:id", {
+        method: "PUT";
+        body: zod.ZodObject<{
+            title: zod.ZodOptional<zod.ZodString>;
+        }, zod_v4_core.$strip>;
+    }, Conversation>;
+    deleteConversation: better_call.StrictEndpoint<"/chat/conversations/:id", {
+        method: "DELETE";
+    }, {
+        success: boolean;
+    }>;
+}, {
+    getAllConversations: (userId?: string) => Promise<Conversation[]>;
+    getConversationById: (id: string) => Promise<(Conversation & {
+        messages: Message[];
+    }) | null>;
+}>;
+type AiChatApiRouter = ReturnType<ReturnType<typeof aiChatBackendPlugin>["routes"]>;
+
+type ConversationWithMessages = SerializedConversation & {
+    messages: SerializedMessage[];
+};
+declare function createAiChatQueryKeys(client: ReturnType<typeof createApiClient<AiChatApiRouter>>, headers?: HeadersInit): {
+    conversations: {
+        _def: readonly ["conversations"];
+    } & {
+        list: (() => Omit<{
+            queryKey: readonly ["conversations", "list", string];
+            queryFn: _tanstack_react_query.QueryFunction<SerializedConversation[], readonly ["conversations", "list", string]>;
+        } & {
+            _def: readonly ["conversations", "list"];
+        }, "_def">) & {
+            _def: readonly ["conversations", "list"];
+        };
+        detail: ((id: string) => Omit<{
+            queryKey: readonly ["conversations", "detail", string];
+            queryFn: _tanstack_react_query.QueryFunction<ConversationWithMessages | null, readonly ["conversations", "detail", string]>;
+        } & {
+            _def: readonly ["conversations", "detail"];
+        }, "_def">) & {
+            _def: readonly ["conversations", "detail"];
+        };
+    };
+};
+
+export { createAiChatQueryKeys as c, aiChatBackendPlugin as d };
+export type { AiChatBackendHooks as A, ChatApiContext as C, AiChatMode as a, AiChatBackendConfig as b, AiChatApiRouter as e, ConversationWithMessages as f };

package/dist/shared/{stack.DzH_wcvr.d.mts → stack.CIrIsc-A.d.cts}

@@ -66,8 +66,8 @@ interface SerializedFormSubmission extends Omit<FormSubmission, "submittedAt"> {
  * Serialized form submission with parsed data
  */
 interface SerializedFormSubmissionWithData<TData = Record<string, unknown>> extends SerializedFormSubmission {
-    /** Parsed data object (JSON.parse of data field) */
-    parsedData: TData;
+    /** Parsed data object (JSON.parse of data field). Null when the stored JSON is corrupted. */
+    parsedData: TData | null;
     /** Joined form */
     form?: SerializedForm;
 }

package/dist/shared/{stack.DzH_wcvr.d.ts → stack.CIrIsc-A.d.mts}

@@ -66,8 +66,8 @@ interface SerializedFormSubmission extends Omit<FormSubmission, "submittedAt"> {
  * Serialized form submission with parsed data
  */
 interface SerializedFormSubmissionWithData<TData = Record<string, unknown>> extends SerializedFormSubmission {
-    /** Parsed data object (JSON.parse of data field) */
-    parsedData: TData;
+    /** Parsed data object (JSON.parse of data field). Null when the stored JSON is corrupted. */
+    parsedData: TData | null;
     /** Joined form */
     form?: SerializedForm;
 }

package/dist/shared/{stack.DzH_wcvr.d.cts → stack.CIrIsc-A.d.ts}

@@ -66,8 +66,8 @@ interface SerializedFormSubmission extends Omit<FormSubmission, "submittedAt"> {
  * Serialized form submission with parsed data
  */
 interface SerializedFormSubmissionWithData<TData = Record<string, unknown>> extends SerializedFormSubmission {
-    /** Parsed data object (JSON.parse of data field) */
-    parsedData: TData;
+    /** Parsed data object (JSON.parse of data field). Null when the stored JSON is corrupted. */
+    parsedData: TData | null;
     /** Joined form */
     form?: SerializedForm;
 }