@btst/stack 1.3.0 → 1.4.0

package/src/plugins/ai-chat/client/hooks/chat-hooks.tsx

@@ -0,0 +1,349 @@
+"use client";
+
+import { createApiClient } from "@btst/stack/plugins/client";
+import {
+	useMutation,
+	useQuery,
+	useQueryClient,
+	useSuspenseQuery,
+} from "@tanstack/react-query";
+import type { AiChatApiRouter } from "../../api/plugin";
+import {
+	createAiChatQueryKeys,
+	type ConversationWithMessages,
+} from "../../query-keys";
+import type { SerializedConversation, SerializedMessage } from "../../types";
+import { usePluginOverrides } from "@btst/stack/context";
+import type { AiChatPluginOverrides } from "../overrides";
+
+/**
+ * Shared React Query configuration for all chat queries
+ * Prevents automatic refetching to avoid hydration mismatches in SSR
+ */
+const SHARED_QUERY_CONFIG = {
+	retry: false,
+	refetchOnWindowFocus: false,
+	refetchOnMount: false,
+	refetchOnReconnect: false,
+	staleTime: 1000 * 60 * 5, // 5 minutes
+	gcTime: 1000 * 60 * 10, // 10 minutes
+} as const;
+
+/**
+ * Options for the useConversations hook
+ */
+export interface UseConversationsOptions {
+	/** Whether to enable the query (default: true) */
+	enabled?: boolean;
+}
+
+/**
+ * Result from the useConversations hook
+ */
+export interface UseConversationsResult {
+	/** Array of conversations */
+	conversations: SerializedConversation[];
+	/** Whether the initial load is in progress */
+	isLoading: boolean;
+	/** Error if the query failed */
+	error: Error | null;
+	/** Function to refetch the conversations */
+	refetch: () => void;
+}
+
+/**
+ * Hook for fetching all conversations
+ */
+export function useConversations(
+	options: UseConversationsOptions = {},
+): UseConversationsResult {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<AiChatPluginOverrides>("ai-chat");
+	const client = createApiClient<AiChatApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const { enabled = true } = options;
+	const queries = createAiChatQueryKeys(client, headers);
+
+	const listQuery = queries.conversations.list();
+
+	const { data, isLoading, error, refetch } = useQuery<
+		SerializedConversation[],
+		Error,
+		SerializedConversation[],
+		typeof listQuery.queryKey
+	>({
+		...listQuery,
+		...SHARED_QUERY_CONFIG,
+		enabled: enabled && !!client,
+	});
+
+	return {
+		conversations: data ?? [],
+		isLoading,
+		error,
+		refetch,
+	};
+}
+
+/**
+ * Suspense variant of useConversations
+ */
+export function useSuspenseConversations(): {
+	conversations: SerializedConversation[];
+	refetch: () => Promise<unknown>;
+} {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<AiChatPluginOverrides>("ai-chat");
+	const client = createApiClient<AiChatApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const queries = createAiChatQueryKeys(client, headers);
+	const listQuery = queries.conversations.list();
+
+	const { data, refetch, error, isFetching } = useSuspenseQuery<
+		SerializedConversation[],
+		Error,
+		SerializedConversation[],
+		typeof listQuery.queryKey
+	>({
+		...listQuery,
+		...SHARED_QUERY_CONFIG,
+	});
+
+	if (error && !isFetching) {
+		throw error;
+	}
+
+	return {
+		conversations: data ?? [],
+		refetch,
+	};
+}
+
+/**
+ * Options for the useConversation hook
+ */
+export interface UseConversationOptions {
+	/** Whether to enable the query (default: true) */
+	enabled?: boolean;
+}
+
+/**
+ * Result from the useConversation hook
+ */
+export interface UseConversationResult {
+	/** The conversation with messages, or null if not found */
+	conversation: ConversationWithMessages | null;
+	/** Whether the conversation is being loaded */
+	isLoading: boolean;
+	/** Error if the query failed */
+	error: Error | null;
+	/** Function to refetch the conversation */
+	refetch: () => void;
+}
+
+/**
+ * Hook for fetching a single conversation with messages
+ */
+export function useConversation(
+	id?: string,
+	options: UseConversationOptions = {},
+): UseConversationResult {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<AiChatPluginOverrides>("ai-chat");
+	const client = createApiClient<AiChatApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const { enabled = true } = options;
+	const queries = createAiChatQueryKeys(client, headers);
+
+	const detailQuery = queries.conversations.detail(id ?? "");
+
+	const { data, isLoading, error, refetch } = useQuery<
+		ConversationWithMessages | null,
+		Error,
+		ConversationWithMessages | null,
+		typeof detailQuery.queryKey
+	>({
+		...detailQuery,
+		...SHARED_QUERY_CONFIG,
+		enabled: enabled && !!client && !!id,
+	});
+
+	return {
+		conversation: data || null,
+		isLoading,
+		error,
+		refetch,
+	};
+}
+
+/**
+ * Suspense variant of useConversation
+ */
+export function useSuspenseConversation(id: string): {
+	conversation: ConversationWithMessages | null;
+	refetch: () => Promise<unknown>;
+} {
+	const { apiBaseURL, apiBasePath, headers } =
+		usePluginOverrides<AiChatPluginOverrides>("ai-chat");
+	const client = createApiClient<AiChatApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const queries = createAiChatQueryKeys(client, headers);
+	const detailQuery = queries.conversations.detail(id);
+
+	const { data, refetch, error, isFetching } = useSuspenseQuery<
+		ConversationWithMessages | null,
+		Error,
+		ConversationWithMessages | null,
+		typeof detailQuery.queryKey
+	>({
+		...detailQuery,
+		...SHARED_QUERY_CONFIG,
+	});
+
+	if (error && !isFetching) {
+		throw error;
+	}
+
+	return {
+		conversation: data || null,
+		refetch,
+	};
+}
+
+/**
+ * Hook for creating a new conversation
+ */
+export function useCreateConversation() {
+	const { refresh, apiBaseURL, apiBasePath } =
+		usePluginOverrides<AiChatPluginOverrides>("ai-chat");
+	const client = createApiClient<AiChatApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const queryClient = useQueryClient();
+	const queries = createAiChatQueryKeys(client);
+
+	return useMutation<
+		SerializedConversation | null,
+		Error,
+		{ id?: string; title?: string }
+	>({
+		mutationKey: [...queries.conversations._def, "create"],
+		mutationFn: async (data) => {
+			const response = await client("@post/chat/conversations", {
+				method: "POST",
+				body: data,
+			});
+			return response.data as SerializedConversation | null;
+		},
+		onSuccess: async (created) => {
+			// Update list cache
+			await queryClient.invalidateQueries({
+				queryKey: queries.conversations.list().queryKey,
+			});
+			// Refresh server-side cache if available
+			if (refresh) {
+				await refresh();
+			}
+		},
+	});
+}
+
+/**
+ * Hook for renaming a conversation
+ */
+export function useRenameConversation() {
+	const { refresh, apiBaseURL, apiBasePath } =
+		usePluginOverrides<AiChatPluginOverrides>("ai-chat");
+	const client = createApiClient<AiChatApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const queryClient = useQueryClient();
+	const queries = createAiChatQueryKeys(client);
+
+	return useMutation<
+		SerializedConversation | null,
+		Error,
+		{ id: string; title: string }
+	>({
+		mutationKey: [...queries.conversations._def, "rename"],
+		mutationFn: async ({ id, title }) => {
+			const response = await client("@put/chat/conversations/:id", {
+				method: "PUT",
+				params: { id },
+				body: { title },
+			});
+			return response.data as SerializedConversation | null;
+		},
+		onSuccess: async (updated) => {
+			// Update detail cache if available
+			if (updated?.id) {
+				queryClient.setQueryData(
+					queries.conversations.detail(updated.id).queryKey,
+					(old: ConversationWithMessages | null | undefined) =>
+						old ? { ...old, ...updated } : null,
+				);
+			}
+			// Invalidate list
+			await queryClient.invalidateQueries({
+				queryKey: queries.conversations.list().queryKey,
+			});
+			if (refresh) {
+				await refresh();
+			}
+		},
+	});
+}
+
+/**
+ * Hook for deleting a conversation
+ */
+export function useDeleteConversation() {
+	const { refresh, apiBaseURL, apiBasePath } =
+		usePluginOverrides<AiChatPluginOverrides>("ai-chat");
+	const client = createApiClient<AiChatApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	const queryClient = useQueryClient();
+	const queries = createAiChatQueryKeys(client);
+
+	return useMutation<{ success: boolean }, Error, { id: string }>({
+		mutationKey: [...queries.conversations._def, "delete"],
+		mutationFn: async ({ id }) => {
+			const response = await client("@delete/chat/conversations/:id", {
+				method: "DELETE",
+				params: { id },
+			});
+			return response.data as { success: boolean };
+		},
+		onSuccess: async (_, { id }) => {
+			// Remove from detail cache
+			queryClient.removeQueries({
+				queryKey: queries.conversations.detail(id).queryKey,
+			});
+			// Invalidate list
+			await queryClient.invalidateQueries({
+				queryKey: queries.conversations.list().queryKey,
+			});
+			if (refresh) {
+				await refresh();
+			}
+		},
+	});
+}
+
+export type {
+	SerializedConversation,
+	SerializedMessage,
+	ConversationWithMessages,
+};

package/src/plugins/ai-chat/client/hooks/index.tsx

@@ -0,0 +1 @@
+export * from "./chat-hooks";

package/src/plugins/ai-chat/client/index.ts

@@ -0,0 +1,14 @@
+export { aiChatClientPlugin } from "./plugin";
+export type {
+	AiChatClientConfig,
+	AiChatClientHooks,
+	RouteContext,
+	LoaderContext,
+} from "./plugin";
+export type { AiChatPluginOverrides, AllowedFileType } from "./overrides";
+export { DEFAULT_ALLOWED_FILE_TYPES } from "./overrides";
+export { ChatInterface } from "./components/chat-interface";
+export { ChatLayout } from "./components/chat-layout";
+export { ChatSidebar } from "./components/chat-sidebar";
+export { ChatMessage } from "./components/chat-message";
+export { ChatInput } from "./components/chat-input";

package/src/plugins/ai-chat/client/localization/index.ts

@@ -0,0 +1,156 @@
+/**
+ * AI Chat plugin localization strings
+ */
+export interface AiChatLocalization {
+	// Chat interface
+	CHAT_PLACEHOLDER: string;
+	CHAT_SEND_BUTTON: string;
+	CHAT_EMPTY_STATE: string;
+	CHAT_LOADING: string;
+	CHAT_ERROR: string;
+	CHAT_RETRY: string;
+
+	// Page errors
+	CHAT_GENERIC_ERROR_TITLE: string;
+	CHAT_GENERIC_ERROR_MESSAGE: string;
+	CHAT_PAGE_NOT_FOUND_TITLE: string;
+	CHAT_PAGE_NOT_FOUND_DESCRIPTION: string;
+
+	// Sidebar
+	SIDEBAR_TITLE: string;
+	SIDEBAR_NEW_CHAT: string;
+	SIDEBAR_NO_CONVERSATIONS: string;
+	SIDEBAR_SEARCH_PLACEHOLDER: string;
+
+	// Conversation actions
+	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 (legacy)
+	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
+	FILE_UPLOAD_BUTTON: string;
+	FILE_UPLOAD_ERROR_TOO_LARGE: string;
+	FILE_UPLOAD_SUCCESS: string;
+	FILE_UPLOAD_FAILURE: string;
+
+	// Timestamps
+	TIME_JUST_NOW: string;
+	TIME_MINUTES_AGO: string;
+	TIME_HOURS_AGO: string;
+	TIME_YESTERDAY: string;
+	TIME_DAYS_AGO: string;
+
+	// Message actions
+	MESSAGE_COPY: string;
+	MESSAGE_COPIED: string;
+	MESSAGE_RETRY: string;
+	MESSAGE_EDIT: string;
+	MESSAGE_SAVE: string;
+	MESSAGE_CANCEL: string;
+
+	// Accessibility
+	A11Y_USER_MESSAGE: string;
+	A11Y_ASSISTANT_MESSAGE: string;
+	A11Y_COPY_CODE: string;
+	A11Y_CODE_COPIED: string;
+}
+
+/**
+ * Default English localization strings
+ */
+export const AI_CHAT_LOCALIZATION: AiChatLocalization = {
+	// Chat interface
+	CHAT_PLACEHOLDER: "Type a message...",
+	CHAT_SEND_BUTTON: "Send",
+	CHAT_EMPTY_STATE: "Start a conversation...",
+	CHAT_LOADING: "Thinking...",
+	CHAT_ERROR: "Something went wrong. Please try again.",
+	CHAT_RETRY: "Retry",
+
+	// Page errors
+	CHAT_GENERIC_ERROR_TITLE: "Something went wrong",
+	CHAT_GENERIC_ERROR_MESSAGE:
+		"An error occurred while loading the chat. Please try again.",
+	CHAT_PAGE_NOT_FOUND_TITLE: "Chat not found",
+	CHAT_PAGE_NOT_FOUND_DESCRIPTION:
+		"The conversation you're looking for doesn't exist or has been deleted.",
+
+	// Sidebar
+	SIDEBAR_TITLE: "Conversations",
+	SIDEBAR_NEW_CHAT: "New chat",
+	SIDEBAR_NO_CONVERSATIONS: "No conversations yet",
+	SIDEBAR_SEARCH_PLACEHOLDER: "Search conversations...",
+
+	// Conversation actions
+	CONVERSATION_RENAME: "Rename",
+	CONVERSATION_RENAME_PLACEHOLDER: "Enter conversation name",
+	CONVERSATION_RENAME_SAVE: "Save",
+	CONVERSATION_RENAME_CANCEL: "Cancel",
+	CONVERSATION_DELETE: "Delete",
+	CONVERSATION_DELETE_CONFIRM_TITLE: "Delete conversation",
+	CONVERSATION_DELETE_CONFIRM_DESCRIPTION:
+		"Are you sure you want to delete this conversation? This action cannot be undone.",
+	CONVERSATION_DELETE_CONFIRM_BUTTON: "Delete",
+	CONVERSATION_DELETE_CANCEL: "Cancel",
+
+	// Image upload (legacy)
+	IMAGE_UPLOAD_BUTTON: "Attach image",
+	IMAGE_UPLOAD_UPLOADING: "Uploading...",
+	IMAGE_UPLOAD_ERROR_NOT_IMAGE: "Please select an image file",
+	IMAGE_UPLOAD_ERROR_TOO_LARGE: "Image must be less than 4MB",
+	IMAGE_UPLOAD_SUCCESS: "Image uploaded",
+	IMAGE_UPLOAD_FAILURE: "Failed to upload image",
+
+	// File upload
+	FILE_UPLOAD_BUTTON: "Attach file",
+	FILE_UPLOAD_ERROR_TOO_LARGE: "File must be less than 10MB",
+	FILE_UPLOAD_SUCCESS: "File attached",
+	FILE_UPLOAD_FAILURE: "Failed to attach file",
+
+	// Timestamps
+	TIME_JUST_NOW: "Just now",
+	TIME_MINUTES_AGO: "{count} minutes ago",
+	TIME_HOURS_AGO: "{count} hours ago",
+	TIME_YESTERDAY: "Yesterday",
+	TIME_DAYS_AGO: "{count} days ago",
+
+	// Message actions
+	MESSAGE_COPY: "Copy message",
+	MESSAGE_COPIED: "Copied!",
+	MESSAGE_RETRY: "Retry",
+	MESSAGE_EDIT: "Edit message",
+	MESSAGE_SAVE: "Save",
+	MESSAGE_CANCEL: "Cancel",
+
+	// Accessibility
+	A11Y_USER_MESSAGE: "Your message",
+	A11Y_ASSISTANT_MESSAGE: "AI response",
+	A11Y_COPY_CODE: "Copy code",
+	A11Y_CODE_COPIED: "Code copied",
+};
+
+/**
+ * Helper function to format localized strings with placeholders
+ */
+export function formatLocalized(
+	template: string,
+	values: Record<string, string | number>,
+): string {
+	return template.replace(/\{(\w+)\}/g, (match, key) => {
+		return values[key]?.toString() ?? match;
+	});
+}

package/src/plugins/ai-chat/client/overrides.ts

@@ -0,0 +1,170 @@
+import type { ComponentType } from "react";
+import type { AiChatLocalization } from "./localization";
+
+/**
+ * Plugin mode for AI Chat
+ * - 'authenticated': Conversations persisted with userId (default)
+ * - 'public': Stateless chat, no persistence (ideal for public chatbots)
+ */
+export type AiChatMode = "authenticated" | "public";
+
+/**
+ * Allowed file type categories for uploads
+ */
+export 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
+ */
+export const DEFAULT_ALLOWED_FILE_TYPES: AllowedFileType[] = ["image"];
+
+/**
+ * MIME type mappings for each file type category
+ */
+export const FILE_TYPE_MIME_MAP: Record<AllowedFileType, string[]> = {
+	image: ["image/*"],
+	text: ["text/plain"],
+	markdown: ["text/markdown"],
+	csv: ["text/csv"],
+	pdf: ["application/pdf"],
+	json: ["application/json"],
+};
+
+/**
+ * Context passed to lifecycle hooks
+ */
+export 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;
+}
+
+/**
+ * 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.)
+ */
+export 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;
+
+	// ============== Lifecycle Hooks (optional) ==============
+
+	/**
+	 * 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,
+	) => 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,
+	) => 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) => 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,
+	) => boolean;
+}