andy-widget-react 2.2.1 → 2.3.1

package/dist/types/types/index.d.ts

@@ -60,7 +60,8 @@ export interface UserInfo {
     name: string;
     email: string;
 }
-export interface AndyChatProps {
+export interface SalesAndyChatProps {
+    mode?: 'sales';
     /** Required chatbot embed ID (not required if previewMode is true) */
     embedId?: string;
     /** Optional tooltip text for the chat bubble */
@@ -96,6 +97,15 @@ export interface AndyChatProps {
     /** If true, start with chat window open */
     initialOpen?: boolean;
 }
+export interface SupportAndyChatProps {
+    mode: 'support';
+    support: import('andy-widget-core').SupportOptions;
+    lang?: 'es' | 'en';
+    orientation?: 'left' | 'right';
+    initialOpen?: boolean;
+    tooltip?: string;
+}
+export type AndyChatProps = SalesAndyChatProps | SupportAndyChatProps;
 export interface FaqItemProps {
     question: string;
     answer: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "andy-widget-react",
-	"version": "2.2.1",
+	"version": "2.3.1",
 	"description": "Official React Widget for embeddable Andy agents",
 	"type": "module",
 	"main": "dist/index.cjs",
@@ -67,6 +67,6 @@
 		"react-dom": "^18.0.0 || ^19.0.0"
 	},
 	"dependencies": {
-		"andy-widget-core": "2.2.1"
+		"andy-widget-core": "2.3.1"
 	}
 }

package/src/AndyChat.tsx

@@ -22,7 +22,8 @@ import {
 	isMobileDevice
 } from 'andy-widget-core'
 
-import type { AndyChatProps, ChatbotConfig, Message } from './types'
+import type { AndyChatProps, SalesAndyChatProps, ChatbotConfig, Message } from './types'
+import { SupportChat } from './SupportChat'
 
 interface FaqItemProps {
 	question: string
@@ -65,7 +66,7 @@ const FaqItem: React.FC<FaqItemProps> = ({ question, answer }) => {
 	)
 }
 
-const AndyChat: React.FC<AndyChatProps> = ({
+const SalesAndyChat: React.FC<SalesAndyChatProps> = ({
 	embedId,
 	tooltip,
 	name,
@@ -1142,4 +1143,8 @@ const AndyChat: React.FC<AndyChatProps> = ({
 	)
 }
 
+const AndyChat: React.FC<AndyChatProps> = props => props.mode === 'support'
+	? <SupportChat key={`${props.support.installationId}:${props.support.contextKey}`} {...props} />
+	: <SalesAndyChat {...props} />
+
 export default AndyChat

package/src/SupportChat.tsx

@@ -0,0 +1,106 @@
+import React, { useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import { generateDesignTokenVariablesString, getContrastTextColor, getSupportStylesheet, type SupportTicket } from 'andy-widget-core'
+import type { SupportAndyChatProps } from './types'
+import { useSupportChat } from './hooks/useSupportChat'
+
+const copy = {
+	es: { support: 'Soporte', close: 'Cerrar', back: 'Volver', menu: 'Menú', new: 'Nueva conversación', team: 'Hablar con el equipo', requests: 'Mis solicitudes', placeholder: '¿En qué te podemos ayudar?', send: 'Enviar', subject: 'Asunto', detail: 'Cuéntanos qué ocurrió', notice: 'Se adjuntará esta conversación', consent: 'Al enviar, aceptas adjuntar esta conversación para que el equipo pueda ayudarte.', submit: 'Enviar solicitud', receipt: 'Solicitud enviada', promise: 'El equipo responderá en', businessDay: 'un día hábil', hours: 'horas hábiles', minutes: 'minutos hábiles', empty: 'Todavía no tienes solicitudes.', powered: 'Con tecnología de Andy', loading: 'Cargando…', retry: 'Reintentar', error: 'No pudimos completar la solicitud. Puedes reintentar.', auth: 'Tu sesión de soporte no está disponible. Vuelve a iniciar sesión en esta aplicación.', denied: 'El soporte no está disponible para esta cuenta.', transcript: 'mensajes', transcriptSingular: 'mensaje', reply: 'Escribe tu respuesta', reopen: 'Reabrir', reopening: 'Cuéntanos qué volvió a ocurrir', otherProblem: 'Es otro problema', reopened: 'Reabierto', unread: 'Respuestas sin leer', resolvedReply: 'Esta solicitud está resuelta. Reábrela para continuar con el mismo problema.', open: 'Recibido', in_progress: 'En curso', waiting_customer: 'Espera tu respuesta', resolved: 'Resuelto' },
+	en: { support: 'Support', close: 'Close', back: 'Back', menu: 'Menu', new: 'New conversation', team: 'Talk to the team', requests: 'My requests', placeholder: 'How can we help?', send: 'Send', subject: 'Subject', detail: 'Tell us what happened', notice: 'This conversation will be attached', consent: 'By sending, you agree to attach this conversation so the team can help you.', submit: 'Send request', receipt: 'Request sent', promise: 'The team will reply within', businessDay: 'one business day', hours: 'business hours', minutes: 'business minutes', empty: 'You have no requests yet.', powered: 'Powered by Andy', loading: 'Loading…', retry: 'Retry', error: 'We could not complete the request. You can retry.', auth: 'Your support session is unavailable. Sign in again in this application.', denied: 'Support is unavailable for this account.', transcript: 'messages', transcriptSingular: 'message', reply: 'Write your reply', reopen: 'Reopen', reopening: 'Tell us what happened again', otherProblem: 'This is another problem', reopened: 'Reopened', unread: 'Unread replies', resolvedReply: 'This request is resolved. Reopen it to continue with the same problem.', open: 'Received', in_progress: 'In progress', waiting_customer: 'Waiting for your reply', resolved: 'Resolved' }
+}
+
+/** Private Requester UI. Sales bootstrap, visitor identity and storage never enter this renderer. */
+const SupportPanel: React.FC<SupportAndyChatProps> = ({ support, lang, orientation = 'right', initialOpen = false, tooltip }) => {
+	const { state, controller } = useSupportChat({ ...support, lang: lang || support.lang })
+	const replyLanguage = lang || support.lang || state.config?.defaultLang || 'es'
+	const strings = copy[replyLanguage]
+	const [open, setOpen] = useState(initialOpen)
+	const [menu, setMenu] = useState(false)
+	const [draft, setDraft] = useState('')
+	const [subject, setSubject] = useState('')
+	const [body, setBody] = useState('')
+	const [replyDraft, setReplyDraft] = useState('')
+	const [reopening, setReopening] = useState(false)
+	const [selectedTicketId, setSelectedTicketId] = useState<string | null>(null)
+	const host = useRef<HTMLDivElement>(null)
+	const messages = useRef<HTMLDivElement>(null)
+	const [portal, setPortal] = useState<HTMLDivElement | null>(null)
+	useEffect(() => {
+		if (!host.current) return
+		const shadow = host.current.shadowRoot || host.current.attachShadow({ mode: 'open' })
+		const style = document.createElement('style')
+		style.textContent = generateDesignTokenVariablesString() + getSupportStylesheet()
+		const target = document.createElement('div')
+		shadow.append(style, target)
+		setPortal(target)
+		return () => { style.remove(); target.remove() }
+	}, [])
+	useEffect(() => {
+		const color = state.config?.branding.color || '#171717'
+		host.current?.style.setProperty('--andy-support-color', color)
+		host.current?.style.setProperty('--andy-support-contrast', getContrastTextColor(color))
+	}, [state.config?.branding.color])
+	useEffect(() => { messages.current?.scrollTo?.({ top: messages.current.scrollHeight, behavior: 'smooth' }) }, [state.messages, state.view])
+	useEffect(() => { controller?.setVisible(open) }, [controller, open])
+	useEffect(() => { if (support.ticketId) setOpen(true) }, [support.ticketId])
+	useEffect(() => { if (state.ticket?.status !== 'resolved' && state.followup?.action !== 'reopen') setReopening(false) }, [state.ticket?.status, state.followup?.action])
+	const choose = (action: () => void) => { setMenu(false); action() }
+	const escalate = () => { setSubject(''); setBody(''); controller?.escalate() }
+	const send = () => { if (!draft.trim() || state.busy) return; void controller?.send(draft); setDraft('') }
+	const newProblem = () => { setSubject(''); setBody(''); setReplyDraft(''); setReopening(false); controller?.newProblem() }
+	const followup = async () => {
+		const result = await controller?.reply(replyDraft, reopening)
+		if (result) { setReplyDraft(''); setReopening(false) }
+	}
+	const unread = <span className='andy-support__unread' role='img' aria-label={strings.unread} />
+	const title = state.config?.branding.name || strings.support
+	const ticketRow = (ticket: SupportTicket) => <button key={ticket.id} type='button' className='andy-support__ticket' onClick={() => { setSelectedTicketId(ticket.id); setReplyDraft(''); setReopening(false); void controller?.inspect(ticket.id) }}><span>#{ticket.number} · {ticket.subject} {ticket.unread && unread}</span><small>{strings[ticket.status]}</small><span aria-hidden='true'>›</span></button>
+	const retry = () => {
+		if (!state.config) void controller?.bootstrap()
+		else if (state.view === 'form') void controller?.submit(subject, body, replyLanguage)
+		else if (state.view === 'requests') void controller?.showRequests()
+		else if (state.view === 'request' && state.followup) void followup()
+		else if (state.view === 'request' && (selectedTicketId || support.ticketId)) void controller?.inspect((selectedTicketId || support.ticketId)!)
+	}
+	const errorText = state.error === 'ticket_resolved' ? strings.resolvedReply : ['expired', 'unknown_key', 'malformed', 'authentication_required', 'invalid_signature'].includes(state.error || '') ? strings.auth : state.error === 'permission_denied' ? strings.denied : strings.error
+	const promise = state.ticket?.replyPromise || state.config?.replyPromise
+	const promiseText = !promise ? null : promise.minutes === promise.businessDayMinutes ? strings.businessDay : promise.minutes % 60 === 0 ? `${promise.minutes / 60} ${strings.hours}` : `${promise.minutes} ${strings.minutes}`
+	return <div ref={host} className={`andy-support-host andy-support-host--${orientation}`}>
+		{portal && createPortal(<div className='andy-support' data-private data-ph-no-capture data-sentry-block lang={replyLanguage}>
+			{!open && <button type='button' className='andy-support__launcher' title={tooltip} onClick={() => setOpen(true)}><span>{strings.support} · {title} {state.unreadCount > 0 && unread}</span><span aria-hidden='true'>↗</span></button>}
+			{open && <section className='andy-support__panel' role='dialog' aria-label={`${strings.support} · ${title}`}>
+				<header className='andy-support__header'>
+					{state.view !== 'conversation' && <button type='button' aria-label={strings.back} onClick={() => state.view === 'request' ? void controller?.showRequests() : controller?.back()}>‹</button>}
+					<span className='andy-support__mark' aria-hidden='true'>{title.slice(0, 1)}</span><div className='andy-support__identity'><strong>{title}</strong><small>{strings.support}</small></div>
+					<button type='button' aria-label={strings.menu} aria-expanded={menu} disabled={!state.config} onClick={() => setMenu(!menu)}>···</button><button type='button' aria-label={strings.close} onClick={() => setOpen(false)}>×</button>
+					{menu && <nav className='andy-support__menu' aria-label={strings.menu}><button type='button' onClick={() => choose(() => controller?.newConversation())}>{strings.new}</button><button type='button' onClick={() => choose(escalate)}>{strings.team}</button><button type='button' onClick={() => choose(() => void controller?.showRequests())}>{strings.requests} {state.unreadCount > 0 && unread}</button></nav>}
+				</header>
+				<div className='andy-support__content' ref={messages}>
+					{state.loading && <p role='status'>{strings.loading}</p>}
+					{state.view === 'conversation' && <>
+						{state.messages.map((message, index) => <div key={index} className={`andy-support__message andy-support__message--${message.role}`}>{message.content}</div>)}
+						{state.config && state.messages.length === 1 && <div className='andy-support__questions'>{state.config.questions.map(question => <button type='button' key={question} disabled={state.busy} onClick={() => void controller?.send(question)}>{question}</button>)}</div>}
+						{state.busy && <p className='andy-support__muted' role='status'>···</p>}
+						{state.messages.length > 1 && !state.busy && <button type='button' className='andy-support__secondary' onClick={escalate}>{strings.team} ↗</button>}
+					</>}
+					{state.view === 'form' && <form className='andy-support__form' onSubmit={event => { event.preventDefault(); void controller?.submit(subject, body, replyLanguage) }}>
+						<h2>{strings.team}</h2><label>{strings.subject}<input required maxLength={200} value={state.submission?.subject ?? subject} readOnly={!!state.submission} disabled={state.busy} onChange={event => setSubject(event.target.value)} /></label><label>{strings.detail}<textarea required maxLength={20000} rows={5} value={state.submission?.body ?? body} readOnly={!!state.submission} disabled={state.busy} onChange={event => setBody(event.target.value)} /></label>
+						<details className='andy-support__transcript'><summary>{strings.notice} · {state.transcript.length} {state.transcript.length === 1 ? strings.transcriptSingular : strings.transcript}</summary>{state.transcript.map((message, index) => <p key={index}>{message.content}</p>)}</details><p className='andy-support__muted'>{strings.consent}</p><button type='submit' className='andy-support__primary' disabled={state.busy || !subject.trim() || !body.trim()}>{state.busy ? strings.loading : strings.submit}</button>
+					</form>}
+					{state.view === 'receipt' && state.ticket && <div className='andy-support__receipt'><span className='andy-support__check' aria-hidden='true'>✓</span><h2>{strings.receipt}</h2><strong>#{state.ticket.number}</strong><p>{state.ticket.subject}</p>{promiseText && <p>{strings.promise} <strong>{promiseText}</strong>.</p>}<button type='button' className='andy-support__primary' onClick={() => void controller?.showRequests()}>{strings.requests}</button></div>}
+					{state.view === 'requests' && <><h2>{strings.requests}</h2>{state.tickets.map(ticketRow)}{!state.busy && !state.error && !state.tickets.length && <p className='andy-support__muted'>{strings.empty}</p>}</>}
+					{state.view === 'request' && state.ticket && <><h2>#{state.ticket.number} · {state.ticket.subject}</h2><p className='andy-support__muted'>{strings[state.ticket.status]}{state.ticket.reopened && ` · ${strings.reopened}`}</p>{state.entries.filter(entry => ['requester_message', 'public_reply'].includes(entry.kind)).map(entry => <article className='andy-support__entry' key={entry.id}><strong>{entry.authorName}</strong><p>{entry.body}</p></article>)}
+						{state.ticket.status === 'resolved' && !reopening && <div className='andy-support__request-actions'><button type='button' className='andy-support__primary' onClick={() => setReopening(true)}>{strings.reopen}</button><button type='button' className='andy-support__secondary' onClick={newProblem}>{strings.otherProblem}</button></div>}
+					</>}
+					{state.error && <div className='andy-support__error' role='alert'><p>{errorText}</p>{(!state.config || state.view === 'form' || state.view === 'requests' || (state.view === 'request' && state.error !== 'ticket_resolved' && (selectedTicketId || support.ticketId))) && <button type='button' onClick={retry} disabled={state.busy}>{strings.retry}</button>}</div>}
+				</div>
+				{state.view === 'conversation' && <form className='andy-support__composer' onSubmit={event => { event.preventDefault(); send() }}><input aria-label={strings.placeholder} placeholder={strings.placeholder} value={draft} maxLength={10000} disabled={!state.config} onChange={event => setDraft(event.target.value)} /><button type='submit' aria-label={strings.send} disabled={state.busy || !state.config || !draft.trim()}>↑</button></form>}
+				{state.view === 'request' && state.ticket && (state.ticket.status !== 'resolved' || reopening) && <form className='andy-support__followup' onSubmit={event => { event.preventDefault(); void followup() }}><label>{reopening ? strings.reopening : strings.reply}<textarea rows={3} maxLength={20000} required value={state.followup?.body ?? replyDraft} readOnly={!!state.followup} disabled={state.busy} onChange={event => setReplyDraft(event.target.value)} /></label><button type='submit' className='andy-support__primary' disabled={state.busy || !replyDraft.trim()}>{state.busy ? strings.loading : reopening ? strings.reopen : strings.send}</button></form>}
+				<footer className='andy-support__footer'><span>{strings.powered}</span>{state.config?.branding.footer.map(link => <a key={link.url} href={link.url} target='_blank' rel='noopener noreferrer'>{link.label}</a>)}</footer>
+			</section>}
+		</div>, portal)}
+	</div>
+}
+
+/** A host identity change also destroys local drafts and menu state before the next render. */
+export const SupportChat: React.FC<SupportAndyChatProps> = props => <SupportPanel key={JSON.stringify([props.support.installationId, props.support.contextKey, props.support.apiBaseUrl])} {...props} />

package/src/hooks/useAndyChat.ts

@@ -11,11 +11,13 @@ import {
 	CONFIG
 } from 'andy-widget-core'
 import type { ChatbotConfig, Message, UserInfo, UseAndyChatReturn } from '../types'
+import type { SupportOptions } from 'andy-widget-core'
+import { useSupportChat } from './useSupportChat'
 
 const { SESSION_STORAGE_KEY, FORM_DISPLAY_DELAY_MS, PERSIST_SESSION } = CONFIG
 
-export const useAndyChat = (embedId: string): UseAndyChatReturn => {
-	initializeConfig('andy-widget-react')
+const useSalesAndyChat = (embedId: string, enabled: boolean): UseAndyChatReturn => {
+	if (enabled) initializeConfig('andy-widget-react')
 
 	const [config, setConfig] = useState<Partial<ChatbotConfig>>({})
 	const [isLoading, setIsLoading] = useState(true)
@@ -41,6 +43,7 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 	const userInfoTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
 
 	const initializeChatbot = useCallback(async () => {
+		if (!enabled) return
 		if (!embedId) {
 			throw new Error('Embed ID is required')
 		}
@@ -91,7 +94,7 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 			setIsLoading(false)
 			throw err
 		}
-	}, [embedId])
+	}, [embedId, enabled])
 
 	const toggleChat = useCallback(() => {
 		setIsOpen(prev => {
@@ -133,7 +136,7 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 
 	const sendMessage = useCallback(
 		async (messageText: string) => {
-			if (!messageText.trim() || !config || !sessionId || activeReplyRef.current) {
+			if (!enabled || !messageText.trim() || !config || !sessionId || activeReplyRef.current) {
 				return
 			}
 
@@ -184,7 +187,7 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 				if (activeReplyRef.current === controller) activeReplyRef.current = null
 			}
 		},
-		[embedId, sessionId, config]
+		[embedId, sessionId, config, enabled]
 	)
 
 	const showFaq = useCallback(() => {
@@ -213,6 +216,7 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 
 	const submitUserInfo = useCallback(
 		async (userInfo: UserInfo) => {
+			if (!enabled) return
 			try {
 				await submitUserInfoAPI(embedId, sessionId, userInfo)
 				setUserInfoCollected(true)
@@ -231,10 +235,11 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 				throw err
 			}
 		},
-		[embedId, sessionId]
+		[embedId, sessionId, enabled]
 	)
 
 	const startNewSession = useCallback(() => {
+		if (!enabled) return
 		activeReplyRef.current?.abort()
 		activeReplyRef.current = null
 		const newSessionId = generateSessionId()
@@ -265,7 +270,7 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 				setMessages([greetingMessage])
 			}
 		}
-	}, [config])
+	}, [config, enabled])
 
 	const addMessage = useCallback((message: Message) => {
 		setMessages(prev => [...prev, message])
@@ -297,3 +302,11 @@ export const useAndyChat = (embedId: string): UseAndyChatReturn => {
 		addMessage
 	}
 }
+
+export function useAndyChat(embedId: string): UseAndyChatReturn
+export function useAndyChat(options: { mode: 'support'; support: SupportOptions }): ReturnType<typeof useSupportChat>
+export function useAndyChat(input: string | { mode: 'support'; support: SupportOptions }) {
+	const support = useSupportChat(typeof input === 'string' ? null : input.support)
+	const sales = useSalesAndyChat(typeof input === 'string' ? input : '', typeof input === 'string')
+	return typeof input === 'string' ? sales : support
+}

package/src/hooks/useSupportChat.ts

@@ -0,0 +1,29 @@
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import { createSupportController, type SupportOptions, type SupportState } from 'andy-widget-core'
+
+const empty: SupportState = { config: null, view: 'conversation', messages: [], transcript: [], tickets: [], ticket: null, entries: [], loading: true, busy: false, error: null, submission: null, followup: null, unreadCount: 0 }
+const noSubscribe = () => () => {}
+const emptySnapshot = () => empty
+
+/** The host context key changes before a new user/company is allowed to see any previous state. */
+export const useSupportChat = (options: SupportOptions | null) => {
+	const key = options ? JSON.stringify([options.installationId, options.contextKey, options.apiBaseUrl]) : null
+	const callback = useRef(options?.getRequesterPass)
+	callback.current = options?.getRequesterPass
+	const [owned, setOwned] = useState<{ key: string; controller: ReturnType<typeof createSupportController> } | null>(null)
+	const controller = owned?.key === key ? owned?.controller : null
+	const state = useSyncExternalStore(controller?.subscribe || noSubscribe, controller?.getSnapshot || emptySnapshot, emptySnapshot)
+	useEffect(() => {
+		if (!options || !key) return
+		const controller = createSupportController({ ...options, getRequesterPass: () => callback.current!() })
+		setOwned({ key, controller })
+		void controller.bootstrap()
+		return () => controller.dispose()
+	}, [key])
+	useEffect(() => { controller?.setLanguage(options?.lang) }, [controller, options?.lang])
+	const ready = !!state.config
+	useEffect(() => {
+		if (ready && options?.ticketId) void controller?.inspect(options.ticketId)
+	}, [controller, ready, options?.ticketId])
+	return { mode: 'support' as const, state, controller }
+}

package/src/index.ts

@@ -18,6 +18,8 @@ export { default as UserInfoForm } from './components/UserInfoForm'
 // Export types for consumers
 export type {
 	AndyChatProps,
+	SupportAndyChatProps,
+	SalesAndyChatProps,
 	ChatbotConfig,
 	Message,
 	FAQItem,

package/src/types/index.ts

@@ -76,7 +76,8 @@ export interface UserInfo {
 }
 
 // Main AndyChat component props
-export interface AndyChatProps {
+export interface SalesAndyChatProps {
+	mode?: 'sales'
 	/** Required chatbot embed ID (not required if previewMode is true) */
 	embedId?: string
 	/** Optional tooltip text for the chat bubble */
@@ -113,6 +114,16 @@ export interface AndyChatProps {
 	initialOpen?: boolean
 }
 
+export interface SupportAndyChatProps {
+	mode: 'support'
+	support: import('andy-widget-core').SupportOptions
+	lang?: 'es' | 'en'
+	orientation?: 'left' | 'right'
+	initialOpen?: boolean
+	tooltip?: string
+}
+export type AndyChatProps = SalesAndyChatProps | SupportAndyChatProps
+
 // FAQ Item component props
 export interface FaqItemProps {
 	question: string