andy-widget-react 2.0.5

package/src/hooks/useAndyChat.ts

@@ -0,0 +1,281 @@
+import { useState, useCallback, useRef } from 'react'
+import {
+	fetchChatbotConfig,
+	generateSessionId,
+	createGreetingMessage,
+	sendMessage as sendMessageToAPI,
+	submitUserInfo as submitUserInfoAPI,
+	initializeConfig,
+	validateChatbotConfig,
+	normalizeConfig,
+	CONFIG
+} from 'andy-widget-core'
+import type { ChatbotConfig, Message, UserInfo, UseAndyChatReturn } from '../types'
+
+const { SESSION_STORAGE_KEY, FORM_DISPLAY_DELAY_MS, PERSIST_SESSION } = CONFIG
+
+export const useAndyChat = (embedId: string): UseAndyChatReturn => {
+	initializeConfig('andy-widget-react')
+
+	const [config, setConfig] = useState<Partial<ChatbotConfig>>({})
+	const [isLoading, setIsLoading] = useState(true)
+	const [isOpen, setIsOpen] = useState(false)
+	const [error, setError] = useState<string | null>(null)
+
+	const [messages, setMessages] = useState<Message[]>([])
+	const [showingFaq, setShowingFaq] = useState(false)
+	const [sessionId, setSessionId] = useState(() => generateSessionId())
+
+	const [userInfoCollected, setUserInfoCollected] = useState(false)
+	const [showingWelcomePopup, setShowingWelcomePopup] = useState(false)
+	const [showingUserInfoForm, setShowingUserInfoForm] = useState(false)
+	const [welcomePopupShown, setWelcomePopupShown] = useState(false)
+
+	const welcomeTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+	const userInfoTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+	const initializeChatbot = useCallback(async () => {
+		if (!embedId) {
+			throw new Error('Embed ID is required')
+		}
+
+		try {
+			setIsLoading(true)
+			setError(null)
+
+			const rawConfig = await fetchChatbotConfig(embedId)
+
+			const validationResult = validateChatbotConfig(rawConfig)
+			if (!validationResult.isValid) {
+				throw new Error(`Invalid configuration: ${validationResult.errors.join(', ')}`)
+			}
+
+			const normalizedConfig = normalizeConfig(rawConfig as unknown as Record<string, unknown>) as unknown as ChatbotConfig
+			setConfig(normalizedConfig)
+
+			if (PERSIST_SESSION) {
+				const storedSessionId = localStorage.getItem(SESSION_STORAGE_KEY)
+				if (storedSessionId) {
+					setSessionId(storedSessionId)
+				} else {
+					setSessionId(currentSessionId => {
+						localStorage.setItem(SESSION_STORAGE_KEY, currentSessionId)
+						return currentSessionId
+					})
+				}
+			}
+
+			if (normalizedConfig.welcomeMessage) {
+				const greeting = createGreetingMessage(normalizedConfig)
+				if (greeting) {
+					const greetingMessage: Message = {
+						id: Date.now(),
+						content: greeting,
+						sender: 'bot',
+						timestamp: new Date().toISOString()
+					}
+					setMessages([greetingMessage])
+				}
+			}
+
+			setIsLoading(false)
+		} catch (err) {
+			console.error('Failed to initialize chatbot:', err)
+			setError(err instanceof Error ? err.message : 'Unknown error')
+			setIsLoading(false)
+			throw err
+		}
+	}, [embedId])
+
+	const toggleChat = useCallback(() => {
+		setIsOpen(prev => {
+			const newIsOpen = !prev
+
+			if (newIsOpen) {
+				setShowingFaq(false)
+
+				const typedConfig = config as ChatbotConfig
+				if (typedConfig?.showWelcomePopup?.enabled && !welcomePopupShown) {
+					setShowingWelcomePopup(true)
+					setWelcomePopupShown(true)
+				}
+
+				if (typedConfig?.collectUserInfo?.enabled && !userInfoCollected) {
+					if (userInfoTimeoutRef.current) {
+						clearTimeout(userInfoTimeoutRef.current)
+					}
+
+					userInfoTimeoutRef.current = setTimeout(() => {
+						setShowingUserInfoForm(true)
+					}, FORM_DISPLAY_DELAY_MS)
+				}
+			} else {
+				setShowingWelcomePopup(false)
+				setShowingUserInfoForm(false)
+
+				if (welcomeTimeoutRef.current) {
+					clearTimeout(welcomeTimeoutRef.current)
+				}
+				if (userInfoTimeoutRef.current) {
+					clearTimeout(userInfoTimeoutRef.current)
+				}
+			}
+
+			return newIsOpen
+		})
+	}, [config, welcomePopupShown, userInfoCollected])
+
+	const sendMessage = useCallback(
+		async (messageText: string) => {
+			if (!messageText.trim() || !config || !sessionId) {
+				return
+			}
+
+			const userMessage: Message = {
+				id: Date.now(),
+				content: messageText,
+				sender: 'user',
+				timestamp: new Date().toISOString()
+			}
+
+			setMessages(prev => [...prev, userMessage])
+
+			try {
+				const response = await sendMessageToAPI(embedId, sessionId, messageText)
+
+				const botMessage: Message = {
+					id: Date.now() + 1,
+					content: response || 'I apologize, but I encountered an error processing your request.',
+					sender: 'bot',
+					timestamp: new Date().toISOString()
+				}
+
+				setMessages(prev => [...prev, botMessage])
+
+				return response
+			} catch (err) {
+				console.error('Error sending message:', err)
+
+				const errorMessage: Message = {
+					id: Date.now() + 1,
+					content: 'Sorry, I encountered an error. Please try again.',
+					sender: 'bot',
+					timestamp: new Date().toISOString(),
+					isError: true
+				}
+
+				setMessages(prev => [...prev, errorMessage])
+				throw err
+			}
+		},
+		[embedId, sessionId, config]
+	)
+
+	const showFaq = useCallback(() => {
+		setShowingFaq(true)
+	}, [])
+
+	const hideFaq = useCallback(() => {
+		setShowingFaq(false)
+	}, [])
+
+	const showWelcomePopup = useCallback(() => {
+		setShowingWelcomePopup(true)
+	}, [])
+
+	const hideWelcomePopup = useCallback(() => {
+		setShowingWelcomePopup(false)
+	}, [])
+
+	const showUserInfoForm = useCallback(() => {
+		setShowingUserInfoForm(true)
+	}, [])
+
+	const hideUserInfoForm = useCallback(() => {
+		setShowingUserInfoForm(false)
+	}, [])
+
+	const submitUserInfo = useCallback(
+		async (userInfo: UserInfo) => {
+			try {
+				await submitUserInfoAPI(embedId, sessionId, userInfo)
+				setUserInfoCollected(true)
+				setShowingUserInfoForm(false)
+
+				const confirmMessage: Message = {
+					id: Date.now(),
+					content: 'Thank you for providing your information! How can I help you today?',
+					sender: 'bot',
+					timestamp: new Date().toISOString()
+				}
+
+				setMessages(prev => [...prev, confirmMessage])
+			} catch (err) {
+				console.error('Error submitting user info:', err)
+				throw err
+			}
+		},
+		[embedId, sessionId]
+	)
+
+	const startNewSession = useCallback(() => {
+		const newSessionId = generateSessionId()
+		setSessionId(newSessionId)
+
+		if (PERSIST_SESSION) {
+			localStorage.setItem(SESSION_STORAGE_KEY, newSessionId)
+		} else {
+			localStorage.removeItem(SESSION_STORAGE_KEY)
+		}
+
+		setMessages([])
+		setUserInfoCollected(false)
+		setShowingFaq(false)
+		setShowingUserInfoForm(false)
+		setWelcomePopupShown(false)
+
+		const typedConfig = config as ChatbotConfig
+		if (typedConfig?.welcomeMessage) {
+			const greeting = createGreetingMessage(typedConfig)
+			if (greeting) {
+				const greetingMessage: Message = {
+					id: Date.now(),
+					content: greeting,
+					sender: 'bot',
+					timestamp: new Date().toISOString()
+				}
+				setMessages([greetingMessage])
+			}
+		}
+	}, [config])
+
+	const addMessage = useCallback((message: Message) => {
+		setMessages(prev => [...prev, message])
+	}, [])
+
+	return {
+		config,
+		isLoading,
+		isOpen,
+		showingFaq,
+		showingWelcomePopup,
+		showingUserInfoForm,
+		messages,
+		userInfoCollected,
+		sessionId,
+		error,
+
+		initializeChatbot,
+		toggleChat,
+		sendMessage,
+		showFaq,
+		hideFaq,
+		showWelcomePopup,
+		hideWelcomePopup,
+		showUserInfoForm,
+		hideUserInfoForm,
+		submitUserInfo,
+		startNewSession,
+		addMessage
+	}
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+// Main export for AndyChat React package
+export { default as AndyChat } from './AndyChat'
+// Back-compat: older integrations import { Andy } from 'andy-widget-react'
+export { default as Andy } from './AndyChat'
+
+// Export the custom hook for advanced usage
+export { useAndyChat } from './hooks/useAndyChat'
+
+// Export individual components for advanced customization
+export { default as ChatBubble } from './components/ChatBubble'
+export { default as ChatWindow } from './components/ChatWindow'
+export { default as MessageList } from './components/MessageList'
+export { default as MessageInput } from './components/MessageInput'
+export { default as FAQ } from './components/FAQ'
+export { default as WelcomePopup } from './components/WelcomePopup'
+export { default as UserInfoForm } from './components/UserInfoForm'
+
+// Export types for consumers
+export type {
+	AndyChatProps,
+	ChatbotConfig,
+	Message,
+	FAQItem,
+	PredefinedQuestion,
+	WelcomePopupConfig,
+	CollectUserInfoConfig,
+	UserInfo,
+	UseAndyChatReturn,
+	ChatBubbleProps,
+	ChatWindowProps,
+	MessageListProps,
+	MessageInputProps,
+	FAQProps,
+	WelcomePopupProps,
+	UserInfoFormProps,
+	FaqItemProps
+} from './types'
+
+// Re-export core utilities for React users who need them
+export {
+	// Design tokens for custom styling
+	theme,
+	colors,
+	typography,
+	spacing,
+	borderRadius,
+	shadows,
+	zIndex,
+	animation,
+	chat,
+
+	// Utility functions
+	generateSessionId,
+	parseMarkdown,
+	sanitizeUrl,
+
+	// Configuration helpers
+	isValidEmbedId,
+	getEmbedId,
+	getApiBaseUrl,
+	setApiBaseUrl
+} from 'andy-widget-core'
+
+// Default export is the main AndyChat component
+export { default } from './AndyChat'

package/src/styles/main.css

@@ -0,0 +1,14 @@
+/* AndyChat React Styles */
+/* Placeholder CSS file - can be expanded with custom styles */
+
+.andychat-react-container {
+	/* Container styles */
+}
+
+.andychat-bubble {
+	/* Chat bubble styles - handled inline for now */
+}
+
+.andychat-window {
+	/* Chat window styles - handled inline for now */
+}

package/src/types/index.ts

@@ -0,0 +1,222 @@
+/**
+ * Type definitions for andy-widget-react
+ */
+
+// Welcome popup configuration
+export interface WelcomePopupConfig {
+	enabled: boolean
+	seconds: number
+	message?: string
+}
+
+// User info collection configuration
+export interface CollectUserInfoConfig {
+	enabled: boolean
+	message?: string
+}
+
+// Predefined question
+export interface PredefinedQuestion {
+	order: number
+	question: string
+}
+
+// FAQ item
+export interface FAQItem {
+	question: string
+	answer: string
+}
+
+// Core chatbot configuration (matches API response)
+export interface ChatbotConfig {
+	id: string | null
+	name: string
+	theme: 'light' | 'dark' | 'auto'
+	logoUrl: string
+	headline: string
+	brandColor: string
+	description: string
+	orientation: 'left' | 'right'
+	bubbleStyle: 'icon' | 'pill'
+	bubbleLabel: string | null
+	useBrandColor: boolean
+	defaultLang: 'en' | 'es'
+	showBranding: boolean
+	welcomeMessage: string
+	showWelcomePopup: WelcomePopupConfig
+	collectUserInfo: CollectUserInfoConfig
+	predefinedQuestions: PredefinedQuestion[]
+	faqs: FAQItem[]
+}
+
+// Message in the chat
+export interface Message {
+	id: number
+	content: string
+	sender: 'user' | 'bot'
+	timestamp: string
+	isForm?: boolean
+	isLoading?: boolean
+	isError?: boolean
+}
+
+// User info for form submission
+export interface UserInfo {
+	name: string
+	email: string
+}
+
+// Main AndyChat component props
+export interface AndyChatProps {
+	/** Required chatbot embed ID (not required if previewMode is true) */
+	embedId?: string
+	/** Optional tooltip text for the chat bubble */
+	tooltip?: string
+	/** Optional bot name (overrides API value) */
+	name?: string
+	/** Optional headline/subtitle (overrides API value) */
+	headline?: string
+	/** Optional description (overrides API value) */
+	description?: string
+	/** Optional welcome message (overrides API value) */
+	welcomeMessage?: string
+	/** Optional custom label for pill-style bubble (overrides default) */
+	bubbleLabel?: string
+	/** Optional theme ('light' | 'dark' | 'auto') */
+	theme?: 'light' | 'dark' | 'auto'
+	/** Optional position ('left' | 'right') */
+	orientation?: 'left' | 'right'
+	/** Optional brand color hex (e.g., '#3B82F6') */
+	brandColor?: string
+	/** Optional bubble style ('icon' | 'pill') */
+	bubbleStyle?: 'icon' | 'pill'
+	/** Optional whether to use brand color */
+	useBrandColor?: boolean
+	/** Optional logo URL */
+	logoUrl?: string
+	/** If true, skip API fetch and use props directly as config */
+	previewMode?: boolean
+	/** If true, start with chat window open */
+	initialOpen?: boolean
+}
+
+// FAQ Item component props
+export interface FaqItemProps {
+	question: string
+	answer: string
+}
+
+// Chat Bubble component props
+export interface ChatBubbleProps {
+	isOpen: boolean
+	onClick: () => void
+	tooltip?: string
+	logoUrl?: string
+	bubbleStyle?: 'icon' | 'pill'
+	bubbleLabel?: string
+	theme?: 'light' | 'dark' | 'auto'
+	useBrandColor?: boolean
+}
+
+// Chat Window component props
+export interface ChatWindowProps {
+	isOpen: boolean
+	config: ChatbotConfig | null
+	messages: Message[]
+	isLoading: boolean
+	showPredefinedQuestions: boolean
+	isCollectingUserInfo: boolean
+	onClose: () => void
+	onSendMessage: (message: string) => void
+	onPredefinedQuestion: (question: string) => void
+	onUserInfoSubmit: (e: React.FormEvent<HTMLFormElement>) => void
+}
+
+// Message List component props
+export interface MessageListProps {
+	messages: Message[]
+	config: ChatbotConfig | null
+	isLoading: boolean
+	isCollectingUserInfo: boolean
+	onUserInfoSubmit: (e: React.FormEvent<HTMLFormElement>) => void
+}
+
+// Message Input component props
+export interface MessageInputProps {
+	onSendMessage: (message: string) => void
+	disabled?: boolean
+	placeholder?: string
+}
+
+// FAQ component props
+export interface FAQProps {
+	faqs: FAQItem[]
+	onBack: () => void
+}
+
+// Welcome Popup component props
+export interface WelcomePopupProps {
+	message: string
+	orientation?: 'left' | 'right'
+	onClose: () => void
+}
+
+// User Info Form component props
+export interface UserInfoFormProps {
+	message?: string
+	onSubmit: (e: React.FormEvent<HTMLFormElement>) => void
+}
+
+// useAndyChat hook return type
+export interface UseAndyChatReturn {
+	// State
+	config: Partial<ChatbotConfig>
+	isLoading: boolean
+	isOpen: boolean
+	showingFaq: boolean
+	showingWelcomePopup: boolean
+	showingUserInfoForm: boolean
+	messages: Message[]
+	userInfoCollected: boolean
+	sessionId: string
+	error: string | null
+
+	// Actions
+	initializeChatbot: () => Promise<void>
+	toggleChat: () => void
+	sendMessage: (messageText: string) => Promise<unknown>
+	showFaq: () => void
+	hideFaq: () => void
+	showWelcomePopup: () => void
+	hideWelcomePopup: () => void
+	showUserInfoForm: () => void
+	hideUserInfoForm: () => void
+	submitUserInfo: (userInfo: UserInfo) => Promise<void>
+	startNewSession: () => void
+	addMessage: (message: Message) => void
+}
+
+// Stylesheet options for getFullStylesheet
+export interface StylesheetOptions {
+	color?: string
+	useBrandColor?: boolean
+	theme?: 'light' | 'dark' | 'auto'
+	orientation?: 'left' | 'right'
+}
+
+// Host class options for getHostClasses
+export interface HostClassOptions {
+	theme?: 'light' | 'dark' | 'auto'
+	orientation?: 'left' | 'right'
+}
+
+// Keyboard detector listener callback
+export interface KeyboardListenerCallback {
+	(state: { isOpen: boolean; height: number }): void
+}
+
+// Keyboard detector interface
+export interface KeyboardDetector {
+	addListener: (callback: KeyboardListenerCallback) => void
+	removeListener: (callback: KeyboardListenerCallback) => void
+}