@btst/stack 1.3.0 → 1.4.0

package/dist/plugins/ai-chat/query-keys.d.mts

@@ -0,0 +1,478 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import * as zod_v4_core from 'zod/v4/core';
+import * as zod from 'zod';
+import * as better_call from 'better-call';
+import { LanguageModel, Tool } from 'ai';
+import { M as Message, C as Conversation, S as SerializedConversation, a as SerializedMessage } from '../../shared/stack.Be1QIHEn.mjs';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { createApiClient } from '@btst/stack/plugins/client';
+
+/**
+ * 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: {
+        <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
+            body: {
+                messages: ({
+                    role: "system" | "user" | "assistant" | "data";
+                    content: string;
+                    id?: string | undefined;
+                } | {
+                    role: "system" | "user" | "assistant" | "data";
+                    parts: {
+                        [x: string]: unknown;
+                        type: string;
+                        text?: string | undefined;
+                    }[];
+                    id?: string | undefined;
+                    metadata?: any;
+                })[];
+                conversationId?: string | undefined;
+                model?: string | undefined;
+            };
+        } & {
+            method?: "POST" | undefined;
+        } & {
+            query?: Record<string, any> | undefined;
+        } & {
+            params?: Record<string, any>;
+        } & {
+            request?: Request;
+        } & {
+            headers?: HeadersInit;
+        } & {
+            asResponse?: boolean;
+            returnHeaders?: boolean;
+            use?: better_call.Middleware[];
+            path?: string;
+        } & {
+            asResponse?: AsResponse | undefined;
+            returnHeaders?: ReturnHeaders | undefined;
+        }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+            headers: Headers;
+            response: Response;
+        } : Response>;
+        options: {
+            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>;
+        };
+        path: "/chat";
+    };
+    createConversation: {
+        <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
+            body: {
+                id?: string | undefined;
+                title?: string | undefined;
+            };
+        } & {
+            method?: "POST" | undefined;
+        } & {
+            query?: Record<string, any> | undefined;
+        } & {
+            params?: Record<string, any>;
+        } & {
+            request?: Request;
+        } & {
+            headers?: HeadersInit;
+        } & {
+            asResponse?: boolean;
+            returnHeaders?: boolean;
+            use?: better_call.Middleware[];
+            path?: string;
+        } & {
+            asResponse?: AsResponse | undefined;
+            returnHeaders?: ReturnHeaders | undefined;
+        }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+            headers: Headers;
+            response: Conversation;
+        } : Conversation>;
+        options: {
+            method: "POST";
+            body: zod.ZodObject<{
+                id: zod.ZodOptional<zod.ZodString>;
+                title: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>;
+        };
+        path: "/chat/conversations";
+    };
+    listConversations: {
+        <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0?: ({
+            body?: undefined;
+        } & {
+            method?: "GET" | undefined;
+        } & {
+            query?: Record<string, any> | undefined;
+        } & {
+            params?: Record<string, any>;
+        } & {
+            request?: Request;
+        } & {
+            headers?: HeadersInit;
+        } & {
+            asResponse?: boolean;
+            returnHeaders?: boolean;
+            use?: better_call.Middleware[];
+            path?: string;
+        } & {
+            asResponse?: AsResponse | undefined;
+            returnHeaders?: ReturnHeaders | undefined;
+        }) | undefined): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+            headers: Headers;
+            response: Conversation[];
+        } : Conversation[]>;
+        options: {
+            method: "GET";
+        };
+        path: "/chat/conversations";
+    };
+    getConversation: {
+        <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
+            body?: undefined;
+        } & {
+            method?: "GET" | undefined;
+        } & {
+            query?: Record<string, any> | undefined;
+        } & {
+            params: {
+                id: string;
+            };
+        } & {
+            request?: Request;
+        } & {
+            headers?: HeadersInit;
+        } & {
+            asResponse?: boolean;
+            returnHeaders?: boolean;
+            use?: better_call.Middleware[];
+            path?: string;
+        } & {
+            asResponse?: AsResponse | undefined;
+            returnHeaders?: ReturnHeaders | undefined;
+        }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+            headers: Headers;
+            response: Conversation & {
+                messages: Message[];
+            };
+        } : Conversation & {
+            messages: Message[];
+        }>;
+        options: {
+            method: "GET";
+        };
+        path: "/chat/conversations/:id";
+    };
+    updateConversation: {
+        <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
+            body: {
+                title?: string | undefined;
+            };
+        } & {
+            method?: "PUT" | undefined;
+        } & {
+            query?: Record<string, any> | undefined;
+        } & {
+            params: {
+                id: string;
+            };
+        } & {
+            request?: Request;
+        } & {
+            headers?: HeadersInit;
+        } & {
+            asResponse?: boolean;
+            returnHeaders?: boolean;
+            use?: better_call.Middleware[];
+            path?: string;
+        } & {
+            asResponse?: AsResponse | undefined;
+            returnHeaders?: ReturnHeaders | undefined;
+        }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+            headers: Headers;
+            response: Conversation;
+        } : Conversation>;
+        options: {
+            method: "PUT";
+            body: zod.ZodObject<{
+                title: zod.ZodOptional<zod.ZodString>;
+            }, zod_v4_core.$strip>;
+        };
+        path: "/chat/conversations/:id";
+    };
+    deleteConversation: {
+        <AsResponse extends boolean = false, ReturnHeaders extends boolean = false>(inputCtx_0: {
+            body?: undefined;
+        } & {
+            method?: "DELETE" | undefined;
+        } & {
+            query?: Record<string, any> | undefined;
+        } & {
+            params: {
+                id: string;
+            };
+        } & {
+            request?: Request;
+        } & {
+            headers?: HeadersInit;
+        } & {
+            asResponse?: boolean;
+            returnHeaders?: boolean;
+            use?: better_call.Middleware[];
+            path?: string;
+        } & {
+            asResponse?: AsResponse | undefined;
+            returnHeaders?: ReturnHeaders | undefined;
+        }): Promise<[AsResponse] extends [true] ? Response : [ReturnHeaders] extends [true] ? {
+            headers: Headers;
+            response: {
+                success: boolean;
+            };
+        } : {
+            success: boolean;
+        }>;
+        options: {
+            method: "DELETE";
+        };
+        path: "/chat/conversations/:id";
+    };
+}>;
+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 { aiChatBackendPlugin as c, createAiChatQueryKeys };
+export type { AiChatBackendHooks as A, ChatApiContext as C, ConversationWithMessages, AiChatMode as a, AiChatBackendConfig as b, AiChatApiRouter as d };