@btst/stack 1.3.1 → 1.4.0

package/dist/plugins/ai-chat/client/index.d.ts

@@ -0,0 +1,327 @@
+import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
+import * as react from 'react';
+import { ComponentType } from 'react';
+import * as _btst_yar from '@btst/yar';
+import { QueryClient } from '@tanstack/react-query';
+import { S as SerializedConversation, a as SerializedMessage } from '../../../shared/stack.Be1QIHEn.js';
+export { d as ChatInput, C as ChatInterface, a as ChatLayout, c as ChatMessage, b as ChatSidebar } from '../../../shared/stack.DorMi9CZ.js';
+import 'react/jsx-runtime';
+import 'ai';
+
+/**
+ * AI Chat plugin localization strings
+ */
+interface AiChatLocalization {
+    CHAT_PLACEHOLDER: string;
+    CHAT_SEND_BUTTON: string;
+    CHAT_EMPTY_STATE: string;
+    CHAT_LOADING: string;
+    CHAT_ERROR: string;
+    CHAT_RETRY: string;
+    CHAT_GENERIC_ERROR_TITLE: string;
+    CHAT_GENERIC_ERROR_MESSAGE: string;
+    CHAT_PAGE_NOT_FOUND_TITLE: string;
+    CHAT_PAGE_NOT_FOUND_DESCRIPTION: string;
+    SIDEBAR_TITLE: string;
+    SIDEBAR_NEW_CHAT: string;
+    SIDEBAR_NO_CONVERSATIONS: string;
+    SIDEBAR_SEARCH_PLACEHOLDER: string;
+    CONVERSATION_RENAME: string;
+    CONVERSATION_RENAME_PLACEHOLDER: string;
+    CONVERSATION_RENAME_SAVE: string;
+    CONVERSATION_RENAME_CANCEL: string;
+    CONVERSATION_DELETE: string;
+    CONVERSATION_DELETE_CONFIRM_TITLE: string;
+    CONVERSATION_DELETE_CONFIRM_DESCRIPTION: string;
+    CONVERSATION_DELETE_CONFIRM_BUTTON: string;
+    CONVERSATION_DELETE_CANCEL: string;
+    IMAGE_UPLOAD_BUTTON: string;
+    IMAGE_UPLOAD_UPLOADING: string;
+    IMAGE_UPLOAD_ERROR_NOT_IMAGE: string;
+    IMAGE_UPLOAD_ERROR_TOO_LARGE: string;
+    IMAGE_UPLOAD_SUCCESS: string;
+    IMAGE_UPLOAD_FAILURE: string;
+    FILE_UPLOAD_BUTTON: string;
+    FILE_UPLOAD_ERROR_TOO_LARGE: string;
+    FILE_UPLOAD_SUCCESS: string;
+    FILE_UPLOAD_FAILURE: string;
+    TIME_JUST_NOW: string;
+    TIME_MINUTES_AGO: string;
+    TIME_HOURS_AGO: string;
+    TIME_YESTERDAY: string;
+    TIME_DAYS_AGO: string;
+    MESSAGE_COPY: string;
+    MESSAGE_COPIED: string;
+    MESSAGE_RETRY: string;
+    MESSAGE_EDIT: string;
+    MESSAGE_SAVE: string;
+    MESSAGE_CANCEL: string;
+    A11Y_USER_MESSAGE: string;
+    A11Y_ASSISTANT_MESSAGE: string;
+    A11Y_COPY_CODE: string;
+    A11Y_CODE_COPIED: string;
+}
+
+/**
+ * Plugin mode for AI Chat
+ * - 'authenticated': Conversations persisted with userId (default)
+ * - 'public': Stateless chat, no persistence (ideal for public chatbots)
+ */
+type AiChatMode = "authenticated" | "public";
+/**
+ * Allowed file type categories for uploads
+ */
+type AllowedFileType = "image" | "text" | "pdf" | "markdown" | "csv" | "json";
+/**
+ * Default allowed file types (images only for best AI model compatibility)
+ * Consumers can expand this by passing allowedFileTypes in overrides
+ */
+declare const DEFAULT_ALLOWED_FILE_TYPES: AllowedFileType[];
+/**
+ * Context passed to lifecycle hooks
+ */
+interface RouteContext$1 {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { id: "abc123" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Additional context properties */
+    [key: string]: any;
+}
+/**
+ * Overridable components and functions for the AI Chat plugin
+ *
+ * External consumers can provide their own implementations of these
+ * to customize the behavior for their framework (Next.js, React Router, etc.)
+ */
+interface AiChatPluginOverrides {
+    /**
+     * Plugin mode - should match backend config
+     * @default 'authenticated'
+     */
+    mode?: AiChatMode;
+    /**
+     * API base URL
+     */
+    apiBaseURL: string;
+    /**
+     * API base path
+     */
+    apiBasePath: string;
+    /**
+     * Navigation function for programmatic navigation
+     */
+    navigate: (path: string) => void | Promise<void>;
+    /**
+     * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
+     */
+    refresh?: () => void | Promise<void>;
+    /**
+     * Link component for navigation
+     */
+    Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
+    /**
+     * Image component for displaying images
+     */
+    Image?: ComponentType<React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>>;
+    /**
+     * Function used to upload a file and return its URL.
+     * Called for images, PDFs, text files, and other supported file types.
+     */
+    uploadFile?: (file: File) => Promise<string>;
+    /**
+     * Allowed file types for upload.
+     * By default, all types are enabled: image, text, pdf, markdown, csv, json
+     * Set to empty array to disable file uploads entirely.
+     * @default ['image', 'text', 'pdf', 'markdown', 'csv', 'json']
+     */
+    allowedFileTypes?: AllowedFileType[];
+    /**
+     * Localization object for the AI Chat plugin
+     */
+    localization?: Partial<AiChatLocalization>;
+    /**
+     * Optional headers to pass with API requests (e.g., for SSR auth)
+     */
+    headers?: HeadersInit;
+    /**
+     * Whether to show the attribution
+     * @default true
+     */
+    showAttribution?: boolean;
+    /**
+     * Called when a route is rendered
+     * @param routeName - Name of the route (e.g., 'chat', 'chatConversation')
+     * @param context - Route context with path, params, etc.
+     */
+    onRouteRender?: (routeName: string, context: RouteContext$1) => void | Promise<void>;
+    /**
+     * Called when a route encounters an error
+     * @param routeName - Name of the route
+     * @param error - The error that occurred
+     * @param context - Route context
+     */
+    onRouteError?: (routeName: string, error: Error, context: RouteContext$1) => void | Promise<void>;
+    /**
+     * Called before the chat page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param context - Route context
+     */
+    onBeforeChatPageRendered?: (context: RouteContext$1) => boolean;
+    /**
+     * Called before a conversation page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param id - The conversation ID
+     * @param context - Route context
+     */
+    onBeforeConversationPageRendered?: (id: string, context: RouteContext$1) => boolean;
+}
+
+/**
+ * Context passed to route hooks
+ */
+interface RouteContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { id: "abc123" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Additional context properties */
+    [key: string]: any;
+}
+/**
+ * Context passed to loader hooks
+ */
+interface LoaderContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { id: "abc123" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Base URL for API calls */
+    apiBaseURL: string;
+    /** Path where the API is mounted */
+    apiBasePath: string;
+    /** Optional headers for the request */
+    headers?: Headers;
+    /** Additional context properties */
+    [key: string]: any;
+}
+/**
+ * Configuration for AI Chat client plugin
+ */
+interface AiChatClientConfig {
+    /** Base URL for API calls (e.g., "http://localhost:3000") */
+    apiBaseURL: string;
+    /** Path where the API is mounted (e.g., "/api/data") */
+    apiBasePath: string;
+    /** Base URL of your site for SEO meta tags */
+    siteBaseURL: string;
+    /** Path where pages are mounted (e.g., "/pages") */
+    siteBasePath: string;
+    /** React Query client instance for caching */
+    queryClient: QueryClient;
+    /**
+     * Plugin mode - should match backend config
+     * - 'authenticated': Full chat with conversation history (default)
+     * - 'public': Simple widget mode, no persistence, no sidebar
+     * @default 'authenticated'
+     */
+    mode?: AiChatMode;
+    /** Optional SEO configuration for meta tags */
+    seo?: {
+        /** Site name for Open Graph tags */
+        siteName?: string;
+        /** Default description */
+        description?: string;
+        /** Locale for Open Graph (e.g., "en_US") */
+        locale?: string;
+        /** Default image URL for social sharing */
+        defaultImage?: string;
+    };
+    /** Optional hooks for customizing behavior */
+    hooks?: AiChatClientHooks;
+    /** Optional headers for SSR (e.g., forwarding cookies) */
+    headers?: Headers;
+}
+/**
+ * Hooks for AI Chat client plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface AiChatClientHooks {
+    /**
+     * Called before loading conversations list. Return false to cancel loading.
+     * @param context - Loader context with path, params, etc.
+     */
+    beforeLoadConversations?: (context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called after conversations are loaded. Return false to cancel further processing.
+     * @param conversations - Array of loaded conversations or null
+     * @param context - Loader context
+     */
+    afterLoadConversations?: (conversations: SerializedConversation[] | null, context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called before loading a single conversation. Return false to cancel loading.
+     * @param id - Conversation ID being loaded
+     * @param context - Loader context
+     */
+    beforeLoadConversation?: (id: string, context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called after a conversation is loaded. Return false to cancel further processing.
+     * @param conversation - Loaded conversation or null if not found
+     * @param id - Conversation ID that was requested
+     * @param context - Loader context
+     */
+    afterLoadConversation?: (conversation: (SerializedConversation & {
+        messages: SerializedMessage[];
+    }) | null, id: string, context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called when a loading error occurs
+     * @param error - The error that occurred
+     * @param context - Loader context
+     */
+    onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+/**
+ * AI Chat client plugin
+ * Provides routes, components, and React Query hooks for AI chat
+ *
+ * @param config - Configuration including queryClient, baseURL, and optional hooks
+ */
+declare const aiChatClientPlugin: (config: AiChatClientConfig) => _btst_stack_plugins_client.ClientPlugin<Record<string, never>, {
+    chat: {
+        (inputCtx_0?: _btst_yar.InputContext<"/chat", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: react.ComponentType<unknown> | undefined;
+            LoadingComponent?: react.ComponentType<unknown> | undefined;
+            ErrorComponent?: react.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+                property?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+                property?: undefined;
+            } | {
+                property: string;
+                content: string;
+                title?: undefined;
+                name?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/chat";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+}>;
+
+export { DEFAULT_ALLOWED_FILE_TYPES, aiChatClientPlugin };
+export type { AiChatClientConfig, AiChatClientHooks, AiChatPluginOverrides, AllowedFileType, LoaderContext, RouteContext };

package/dist/plugins/ai-chat/client/index.mjs

@@ -0,0 +1,7 @@
+export { aiChatClientPlugin } from '../../../packages/better-stack/src/plugins/ai-chat/client/plugin.mjs';
+export { DEFAULT_ALLOWED_FILE_TYPES } from '../../../packages/better-stack/src/plugins/ai-chat/client/overrides.mjs';
+export { ChatInterface } from '../../../packages/better-stack/src/plugins/ai-chat/client/components/chat-interface.mjs';
+export { ChatLayout } from '../../../packages/better-stack/src/plugins/ai-chat/client/components/chat-layout.mjs';
+export { ChatSidebar } from '../../../packages/better-stack/src/plugins/ai-chat/client/components/chat-sidebar.mjs';
+export { ChatMessage } from '../../../packages/better-stack/src/plugins/ai-chat/client/components/chat-message.mjs';
+export { ChatInput } from '../../../packages/better-stack/src/plugins/ai-chat/client/components/chat-input.mjs';

package/dist/plugins/ai-chat/client.css

@@ -0,0 +1,6 @@
+/* AI Chat Plugin Client Styles */
+/* NOTE:
+ * Markdown + syntax highlighting styles are imported from code (TS/TSX),
+ * matching the blog plugin approach. This avoids brittle nested @import
+ * resolution when consumers import `@btst/stack/plugins/ai-chat/css`.
+ */

package/dist/plugins/ai-chat/query-keys.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+const queryKeyFactory = require('@lukemorales/query-key-factory');
+
+function handleResponse(response) {
+  if (typeof response === "object" && response !== null && "error" in response) {
+    const errorResponse = response;
+    if (errorResponse.error !== null && errorResponse.error !== void 0) {
+      const error = errorResponse.error;
+      if (error instanceof Error) {
+        throw error;
+      }
+      if (typeof error === "object" && error !== null) {
+        const errorObj = error;
+        const message = (typeof errorObj.message === "string" ? errorObj.message : null) || (typeof errorObj.error === "string" ? errorObj.error : null) || JSON.stringify(error);
+        throw new Error(message);
+      }
+      throw new Error(String(error));
+    }
+  }
+  return response.data;
+}
+function createAiChatQueryKeys(client, headers) {
+  const conversations = createConversationsQueries(client, headers);
+  return queryKeyFactory.mergeQueryKeys(conversations);
+}
+function createConversationsQueries(client, headers) {
+  return queryKeyFactory.createQueryKeys("conversations", {
+    // List all conversations
+    list: () => ({
+      // NOTE: query-key-factory already namespaces as:
+      // ["conversations", "list", ...queryKey]
+      // so we use a stable marker (not "list") to avoid ["...","list","list"].
+      queryKey: ["all"],
+      queryFn: async () => {
+        const response = await client("/chat/conversations", {
+          method: "GET",
+          headers
+        });
+        const data = handleResponse(response);
+        return data ?? [];
+      }
+    }),
+    // Get single conversation with messages
+    detail: (id) => ({
+      queryKey: [id],
+      queryFn: async () => {
+        if (!id) return null;
+        const response = await client("/chat/conversations/:id", {
+          method: "GET",
+          params: { id },
+          headers
+        });
+        return handleResponse(response);
+      }
+    })
+  });
+}
+
+exports.createAiChatQueryKeys = createAiChatQueryKeys;