@clivly/chat-widget 0.13.0 → 0.15.0

package/dist/index.cjs

@@ -163,6 +163,13 @@ const WIDGET_STYLES = `
 .clivly-chat-widget textarea {
   font: inherit;
 }
+/* The standalone embed does not load the app's shared stylesheet. */
+@media (width < 48rem), (any-pointer: coarse) {
+  .clivly-chat-widget input,
+  .clivly-chat-widget textarea {
+    font-size: max(16px, 1em);
+  }
+}
 .clivly-chat-widget__launcher {
   align-items: center;
   background: var(--clivly-chat-accent);
@@ -364,6 +371,55 @@ const WIDGET_STYLES = `
   font-size: 0.875rem;
   padding: 0.75rem;
 }
+.clivly-chat-widget__notice {
+  background: var(--clivly-chat-operator);
+  border-radius: 0.8rem;
+  color: var(--clivly-chat-muted);
+  font-size: 0.8125rem;
+  margin: 0;
+  padding: 0.625rem 0.75rem;
+}
+/* Automated and AI messages are marked as such, never styled as a teammate. */
+.clivly-chat-widget__message[data-automation] {
+  background: transparent;
+  border: 1px dashed var(--clivly-chat-border);
+}
+.clivly-chat-widget__badge {
+  border: 1px solid var(--clivly-chat-border);
+  border-radius: 999px;
+  font-size: 0.6875rem;
+  padding: 0 0.4rem;
+}
+.clivly-chat-widget__topics {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.clivly-chat-widget__topic {
+  background: var(--clivly-chat-panel);
+  border: 1px solid var(--clivly-chat-accent);
+  border-radius: 999px;
+  color: var(--clivly-chat-text);
+  cursor: pointer;
+  font-size: 0.875rem;
+  min-height: 2.25rem;
+  padding: 0.4rem 0.85rem;
+}
+.clivly-chat-widget__topic:hover,
+.clivly-chat-widget__topic:focus-visible {
+  background: var(--clivly-chat-visitor);
+}
+.clivly-chat-widget__topic:focus-visible {
+  outline: 2px solid var(--clivly-chat-accent);
+  outline-offset: 2px;
+}
+.clivly-chat-widget__topic[disabled] {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
 .clivly-chat-widget__empty {
   color: var(--clivly-chat-muted);
   font-size: 0.875rem;
@@ -460,8 +516,15 @@ function useResolvedTheme(theme) {
 * protocol reads as a single unit, and so `ChatWidget` stays inside the
 * cognitive-complexity budget.
 */
-function applyServerEvent(event, { setError, setIsReady, setMessages }) {
+function applyServerEvent(event, actions) {
+	const { setError, setIsReady, setMessages } = actions;
 	switch (event.type) {
+		case "assistant.status":
+			actions.setAssistantThinking(event.status === "thinking");
+			return;
+		case "support.state":
+			actions.setSupportState(event.state);
+			return;
 		case "conversation.snapshot":
 			setMessages(sortMessages(event.messages.map((message) => createLocalMessage(message))));
 			return;
@@ -482,14 +545,41 @@ function applyServerEvent(event, { setError, setIsReady, setMessages }) {
 		default: return;
 	}
 }
+/**
+* What a message from the support assistant is called. Automated
+* acknowledgements, AI answers and people are never presented alike, so a
+* visitor is never led to think a person has read their message.
+*/
+const AUTOMATION_BADGES = {
+	ai: "AI assistant",
+	ai_clarify: "AI assistant",
+	greeting: "Automated",
+	handoff: "Automated",
+	topic: "Automated"
+};
+const AUTHOR_LABEL_SUFFIX = / · (?:Automated|AI assistant)$/;
+function automationBadge(message) {
+	if (message.senderType !== "system" || !message.automation) return null;
+	return AUTOMATION_BADGES[message.automation] ?? "Automated";
+}
 function MessageBubble({ message }) {
+	const badge = automationBadge(message);
+	const author = badge ? (message.author ?? "").replace(AUTHOR_LABEL_SUFFIX, "") : message.author;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("article", {
 		className: "clivly-chat-widget__message",
+		"data-automation": badge ? message.automation : void 0,
 		"data-sender": message.senderType,
 		children: [
 			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "clivly-chat-widget__message-meta",
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: message.author ?? "Clivly" }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: formatTimestamp(message.createdAt) })]
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: author || "Clivly" }),
+					badge ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						className: "clivly-chat-widget__badge",
+						children: badge
+					}) : null,
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: formatTimestamp(message.createdAt) })
+				]
 			}),
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { children: message.body }),
 			message.delivery === "sent" ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -516,6 +606,57 @@ function MessageList({ greeting, hasSession, messages }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: messages.map((message) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MessageBubble, { message }, message.id)) });
 }
 /**
+* How often an open, visible widget re-sends its read receipt. The room drops
+* a receipt that arrives within 5 s of the last one, so a reply read in that
+* window would otherwise stay "unread" and be emailed to the visitor.
+*/
+const READ_RECEIPT_REFRESH_MS = 15e3;
+/** How long a visitor waits unanswered before the widget reassures them (D20a). */
+const WAITING_NOTICE_AFTER_MS = 12e4;
+/**
+* When the visitor's latest message was sent, if nobody has answered it yet;
+* null when the latest message is a reply or there is nothing waiting. Failed
+* sends don't count: nobody was notified about them.
+*/
+function awaitingReplySince(messages) {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index];
+		if (!message || message.delivery === "failed") continue;
+		if (message.senderType === "system" || message.automation === "topic_choice") continue;
+		if (message.senderType !== "visitor") return null;
+		return new Date(message.createdAt).getTime();
+	}
+	return null;
+}
+/** True once the visitor has waited `WAITING_NOTICE_AFTER_MS` unanswered. */
+function useWaitingNotice(messages) {
+	const [due, setDue] = (0, react.useState)(false);
+	(0, react.useEffect)(() => {
+		const since = awaitingReplySince(messages);
+		if (since === null) {
+			setDue(false);
+			return;
+		}
+		const remaining = since + WAITING_NOTICE_AFTER_MS - Date.now();
+		if (remaining <= 0) {
+			setDue(true);
+			return;
+		}
+		setDue(false);
+		const timer = setTimeout(() => {
+			setDue(true);
+		}, remaining);
+		return () => {
+			clearTimeout(timer);
+		};
+	}, [messages]);
+	return due;
+}
+function waitingNoticeText(email) {
+	const address = email?.trim();
+	return address ? `We've notified the team — we'll reply here or by email at ${address}.` : "We've notified the team — we'll reply here as soon as we can.";
+}
+/**
 * Whether a seeded visitor is complete enough to skip the form.
 *
 * Both fields have to be present and non-blank: the server requires each, so
@@ -535,6 +676,70 @@ function composerStatusText(hasTransport, isReady) {
 	if (!hasTransport) return "Chat is unavailable";
 	return isReady ? "Conversation ready" : "Connecting…";
 }
+/**
+* Guided options under the greeting. Native buttons in a labelled group, so
+* they are reachable with Tab and operable with Enter/Space; free text stays
+* available beside them the whole time.
+*/
+function SupportTopics({ disabled, onSelect, topics }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+		"aria-label": "Suggested topics",
+		className: "clivly-chat-widget__topics",
+		children: topics.map((topic) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+			className: "clivly-chat-widget__topic",
+			disabled,
+			onClick: () => {
+				onSelect(topic);
+			},
+			type: "button",
+			children: topic.label
+		}) }, topic.id))
+	});
+}
+/** Topics are offered only while automation is answering this conversation. */
+function visibleTopics(session, state) {
+	return state === "automated" ? session?.support?.topics ?? [] : [];
+}
+function composerPlaceholder(hasTopics) {
+	return hasTopics ? "Or type your question" : "Write your message";
+}
+/**
+* Hand one visitor message to the transport: a topic click as `topic.select`
+* when the transport supports it (the server resolves the answer), otherwise
+* as the label, typed. Throws what the transport throws.
+*/
+function dispatchVisitorMessage(transport, clientMessageId, body, topic) {
+	if (topic && transport.selectTopic) {
+		transport.selectTopic({
+			id: clientMessageId,
+			topicId: topic.id,
+			type: "topic.select"
+		});
+		return;
+	}
+	transport.sendMessage({
+		body,
+		id: clientMessageId,
+		type: "message.create"
+	});
+}
+/**
+* One honest status line: the AI is working on an answer, or — once the
+* visitor has waited — that the team has been told. Never both.
+*/
+function StatusNotice({ assistantThinking, email, showWaitingNotice }) {
+	if (assistantThinking) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+		className: "clivly-chat-widget__notice",
+		role: "status",
+		children: "The AI assistant is looking for an answer…"
+	});
+	if (!showWaitingNotice) return null;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+		className: "clivly-chat-widget__notice",
+		role: "status",
+		children: waitingNoticeText(email)
+	});
+}
 function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen = false, launcherLabel = "Chat with us", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
 	const [isOpen, setIsOpen] = (0, react.useState)(initiallyOpen);
 	const [error, setError] = (0, react.useState)(null);
@@ -543,6 +748,8 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 	const [messageDraft, setMessageDraft] = (0, react.useState)("");
 	const [messages, setMessages] = (0, react.useState)([]);
 	const [session, setSession] = (0, react.useState)(null);
+	const [supportState, setSupportState] = (0, react.useState)(null);
+	const [assistantThinking, setAssistantThinking] = (0, react.useState)(false);
 	const [visitor, setVisitor] = (0, react.useState)({
 		email: defaultVisitor?.email ?? "",
 		name: defaultVisitor?.name ?? ""
@@ -553,6 +760,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		if (createTransport) return;
 		console.warn("[clivly] <ChatWidget> was given no createTransport, so messages cannot be sent. Pass createTransport={createClivlyTransport()} — see https://www.npmjs.com/package/@clivly/chat-widget#five-minute-quick-start");
 	}, []);
+	const showWaitingNotice = useWaitingNotice(messages);
 	const themeStyle = useThemeStyle(session, style);
 	const resolvedTheme = useResolvedTheme(theme);
 	(0, react.useEffect)(() => () => {
@@ -572,15 +780,18 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 			handlers: {
 				onClose: () => {
 					setIsReady(false);
+					setAssistantThinking(false);
 				},
 				onError: (transportError) => {
 					setError(transportError.message);
 				},
 				onEvent: (event) => {
 					applyServerEvent(event, {
+						setAssistantThinking,
 						setError,
 						setIsReady,
-						setMessages
+						setMessages,
+						setSupportState
 					});
 				},
 				onOpen: () => {
@@ -595,6 +806,23 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 			if (transportRef.current === connection) transportRef.current = null;
 		};
 	}, [createTransport, session]);
+	(0, react.useEffect)(() => {
+		if (!(isOpen && isReady)) return;
+		const markReadIfVisible = () => {
+			if (document.visibilityState === "visible") transportRef.current?.markRead?.();
+		};
+		markReadIfVisible();
+		const interval = window.setInterval(markReadIfVisible, READ_RECEIPT_REFRESH_MS);
+		document.addEventListener("visibilitychange", markReadIfVisible);
+		return () => {
+			window.clearInterval(interval);
+			document.removeEventListener("visibilitychange", markReadIfVisible);
+		};
+	}, [
+		isOpen,
+		isReady,
+		messages
+	]);
 	const startSession = (0, react.useCallback)(async (identity) => {
 		setError(null);
 		setIsConnecting(true);
@@ -605,6 +833,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 				widgetId
 			});
 			storage?.setItem(createStorageKey(widgetId), nextSession.visitorToken);
+			setSupportState(nextSession.support?.state ?? null);
 			setSession(nextSession);
 			setMessages(sortMessages(nextSession.messages.map((message) => createLocalMessage(message))));
 		} catch (sessionError) {
@@ -637,41 +866,48 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 		session,
 		startSession
 	]);
-	const submitMessage = (event) => {
-		event?.preventDefault();
-		if (!(session && transportRef.current)) {
+	/**
+	* Show the visitor's message at once and hand it to the transport. A topic
+	* click goes as `topic.select` when the transport supports it, so the
+	* server resolves the answer; otherwise as the label, typed.
+	*/
+	const sendVisitorMessage = (body, topic) => {
+		const transport = transportRef.current;
+		if (!(session && transport)) {
 			setError("Chat is not connected yet.");
 			return;
 		}
-		const body = messageDraft.trim();
-		if (!body) return;
 		const clientMessageId = generateId();
 		const optimisticMessage = {
 			author: sessionDisplayName(session),
+			automation: topic && transport.selectTopic ? "topic_choice" : null,
 			body,
 			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
 			id: clientMessageId,
 			senderType: "visitor"
 		};
 		setMessages((currentMessages) => sortMessages([...currentMessages, createLocalMessage(optimisticMessage, "pending")]));
-		setMessageDraft("");
 		setError(null);
 		try {
-			transportRef.current.sendMessage({
-				body,
-				id: clientMessageId,
-				type: "message.create"
-			});
+			dispatchVisitorMessage(transport, clientMessageId, body, topic);
 		} catch (transportError) {
 			const resolved = transportError instanceof Error ? transportError : /* @__PURE__ */ new Error("Failed to send your message.");
 			setMessages((currentMessages) => markMessageFailed(currentMessages, clientMessageId));
 			setError(resolved.message);
 		}
 	};
+	const submitMessage = (event) => {
+		event?.preventDefault();
+		const body = messageDraft.trim();
+		if (!body) return;
+		setMessageDraft("");
+		sendVisitorMessage(body);
+	};
 	const canSend = Boolean(createTransport) && isReady;
 	const greeting = session?.widget.config.greeting ?? "Tell us a little about yourself and we’ll pick up the conversation from there.";
 	const panelTitle = session?.widget.name ?? "Start a conversation";
 	const sessionSummary = sessionSummaryText(session, greeting);
+	const topics = visibleTopics(session, supportState);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: `clivly-chat-widget ${className ?? ""}`.trim(),
 		"data-clivly-theme": resolvedTheme,
@@ -709,16 +945,33 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 						})]
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						"aria-label": "Conversation",
 						className: "clivly-chat-widget__body",
 						ref: listRef,
-						children: [error ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
-							className: "clivly-chat-widget__error",
-							children: error
-						}) : null, /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MessageList, {
-							greeting,
-							hasSession: Boolean(session),
-							messages
-						})]
+						role: "log",
+						children: [
+							error ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "clivly-chat-widget__error",
+								children: error
+							}) : null,
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)(MessageList, {
+								greeting,
+								hasSession: Boolean(session),
+								messages
+							}),
+							topics.length > 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(SupportTopics, {
+								disabled: !canSend,
+								onSelect: (topic) => {
+									sendVisitorMessage(topic.label, topic);
+								},
+								topics
+							}) : null,
+							session ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(StatusNotice, {
+								assistantThinking,
+								email: session.contact?.email,
+								showWaitingNotice
+							}) : null
+						]
 					}),
 					session ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("form", {
 						className: "clivly-chat-widget__composer",
@@ -738,7 +991,7 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 									event.preventDefault();
 									if (messageDraft.trim() && canSend) submitMessage();
 								},
-								placeholder: "Write your message",
+								placeholder: composerPlaceholder(topics.length > 0),
 								value: messageDraft
 							})]
 						}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
@@ -876,6 +1129,13 @@ function createWebSocketTransport({ createSocket = (url, protocols) => new WebSo
 			close: () => {
 				socket.close();
 			},
+			markRead: () => {
+				if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ type: "conversation.read" }));
+			},
+			selectTopic: (event) => {
+				if (socket.readyState !== WebSocket.OPEN) throw new Error("Chat socket is not connected.");
+				socket.send(JSON.stringify(event));
+			},
 			sendMessage: (message) => {
 				if (socket.readyState !== WebSocket.OPEN) throw new Error("Chat socket is not connected.");
 				socket.send(JSON.stringify(message));

package/dist/index.d.cts

@@ -48,11 +48,30 @@ interface WidgetSummary {
 }
 interface WidgetMessage {
   author: string | null;
+  /**
+   * Set on messages the support assistant wrote (`greeting`, `topic`,
+   * `handoff`, `ai`, `ai_clarify`) and on a visitor's topic click
+   * (`topic_choice`). Absent or null on everything a person typed, and on
+   * every message from a server that predates the assistant.
+   */
+  automation?: string | null;
   body: string;
   createdAt: string;
   id: string;
   senderType: WidgetSenderType;
 }
+type WidgetSupportState = "automated" | "handoff" | "human";
+interface WidgetSupportTopic {
+  action: "answer" | "ask" | "link" | "human";
+  id: string;
+  label: string;
+}
+/** Guided support for one conversation. Answers stay on the server. */
+interface WidgetSupport {
+  mode: "human" | "guided" | "ai";
+  state: WidgetSupportState | null;
+  topics: WidgetSupportTopic[];
+}
 interface WidgetSessionPayload {
   contact: WidgetContact | null;
   conversation: WidgetConversation;
@@ -60,6 +79,8 @@ interface WidgetSessionPayload {
   messages: WidgetMessage[];
   /** Absolute socket URL returned by Clivly's bootstrap. */
   socketUrl?: string;
+  /** Absent or null when the widget has no guided support configured. */
+  support?: WidgetSupport | null;
   token: string;
   visitorToken: string;
   widget: WidgetSummary;
@@ -79,7 +100,17 @@ interface WidgetClientCreateMessageEvent {
   id: string;
   type: "message.create";
 }
-type WidgetClientEvent = WidgetClientCreateMessageEvent;
+/** The visitor has seen the thread (see `ChatTransportConnection.markRead`). */
+interface WidgetClientReadEvent {
+  type: "conversation.read";
+}
+/** The visitor picked a guided topic (see `ChatTransportConnection.selectTopic`). */
+interface WidgetClientTopicEvent {
+  id: string;
+  topicId: string;
+  type: "topic.select";
+}
+type WidgetClientEvent = WidgetClientCreateMessageEvent | WidgetClientReadEvent | WidgetClientTopicEvent;
 interface WidgetSessionReadyEvent {
   conversationId: string;
   type: "session.ready";
@@ -98,11 +129,20 @@ interface WidgetMessageAckEvent {
   message: WidgetMessage;
   type: "message.ack";
 }
+interface WidgetSupportStateEvent {
+  state: WidgetSupportState;
+  type: "support.state";
+}
+/** The assistant is preparing an answer (`thinking`) or has finished (`idle`). */
+interface WidgetAssistantStatusEvent {
+  status: "thinking" | "idle";
+  type: "assistant.status";
+}
 interface WidgetErrorEvent {
   message: string;
   type: "error";
 }
-type WidgetServerEvent = WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent;
+type WidgetServerEvent = WidgetAssistantStatusEvent | WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent | WidgetSupportStateEvent;
 //#endregion
 //#region src/transport.d.ts
 interface ChatTransportHandlers {
@@ -113,6 +153,17 @@ interface ChatTransportHandlers {
 }
 interface ChatTransportConnection {
   close: () => void;
+  /**
+   * Tell the server the visitor has seen the thread, so a teammate's reply
+   * they've read isn't also emailed to them. Optional: a custom transport
+   * without it still works, its visitors are just emailed replies they saw.
+   */
+  markRead?: () => void;
+  /**
+   * Send a guided-topic click. Optional: without it the widget sends the
+   * topic's label as an ordinary message, so a custom transport still works.
+   */
+  selectTopic?: (event: WidgetClientTopicEvent) => void;
   sendMessage: (event: WidgetClientCreateMessageEvent) => void;
 }
 interface CreateChatTransportOptions {
@@ -236,4 +287,4 @@ export declare const createClivlyTransport: typeof createClivlyTransport$1;
 export declare const mountChatWidget: typeof mountChatWidget$1;
 export declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 //#endregion
-export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary };
+export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetAssistantStatusEvent, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetClientReadEvent, WidgetClientTopicEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary, WidgetSupport, WidgetSupportState, WidgetSupportStateEvent, WidgetSupportTopic };

package/dist/index.d.mts

@@ -48,11 +48,30 @@ interface WidgetSummary {
 }
 interface WidgetMessage {
   author: string | null;
+  /**
+   * Set on messages the support assistant wrote (`greeting`, `topic`,
+   * `handoff`, `ai`, `ai_clarify`) and on a visitor's topic click
+   * (`topic_choice`). Absent or null on everything a person typed, and on
+   * every message from a server that predates the assistant.
+   */
+  automation?: string | null;
   body: string;
   createdAt: string;
   id: string;
   senderType: WidgetSenderType;
 }
+type WidgetSupportState = "automated" | "handoff" | "human";
+interface WidgetSupportTopic {
+  action: "answer" | "ask" | "link" | "human";
+  id: string;
+  label: string;
+}
+/** Guided support for one conversation. Answers stay on the server. */
+interface WidgetSupport {
+  mode: "human" | "guided" | "ai";
+  state: WidgetSupportState | null;
+  topics: WidgetSupportTopic[];
+}
 interface WidgetSessionPayload {
   contact: WidgetContact | null;
   conversation: WidgetConversation;
@@ -60,6 +79,8 @@ interface WidgetSessionPayload {
   messages: WidgetMessage[];
   /** Absolute socket URL returned by Clivly's bootstrap. */
   socketUrl?: string;
+  /** Absent or null when the widget has no guided support configured. */
+  support?: WidgetSupport | null;
   token: string;
   visitorToken: string;
   widget: WidgetSummary;
@@ -79,7 +100,17 @@ interface WidgetClientCreateMessageEvent {
   id: string;
   type: "message.create";
 }
-type WidgetClientEvent = WidgetClientCreateMessageEvent;
+/** The visitor has seen the thread (see `ChatTransportConnection.markRead`). */
+interface WidgetClientReadEvent {
+  type: "conversation.read";
+}
+/** The visitor picked a guided topic (see `ChatTransportConnection.selectTopic`). */
+interface WidgetClientTopicEvent {
+  id: string;
+  topicId: string;
+  type: "topic.select";
+}
+type WidgetClientEvent = WidgetClientCreateMessageEvent | WidgetClientReadEvent | WidgetClientTopicEvent;
 interface WidgetSessionReadyEvent {
   conversationId: string;
   type: "session.ready";
@@ -98,11 +129,20 @@ interface WidgetMessageAckEvent {
   message: WidgetMessage;
   type: "message.ack";
 }
+interface WidgetSupportStateEvent {
+  state: WidgetSupportState;
+  type: "support.state";
+}
+/** The assistant is preparing an answer (`thinking`) or has finished (`idle`). */
+interface WidgetAssistantStatusEvent {
+  status: "thinking" | "idle";
+  type: "assistant.status";
+}
 interface WidgetErrorEvent {
   message: string;
   type: "error";
 }
-type WidgetServerEvent = WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent;
+type WidgetServerEvent = WidgetAssistantStatusEvent | WidgetConversationSnapshotEvent | WidgetErrorEvent | WidgetMessageAckEvent | WidgetMessageCreatedEvent | WidgetSessionReadyEvent | WidgetSupportStateEvent;
 //#endregion
 //#region src/transport.d.ts
 interface ChatTransportHandlers {
@@ -113,6 +153,17 @@ interface ChatTransportHandlers {
 }
 interface ChatTransportConnection {
   close: () => void;
+  /**
+   * Tell the server the visitor has seen the thread, so a teammate's reply
+   * they've read isn't also emailed to them. Optional: a custom transport
+   * without it still works, its visitors are just emailed replies they saw.
+   */
+  markRead?: () => void;
+  /**
+   * Send a guided-topic click. Optional: without it the widget sends the
+   * topic's label as an ordinary message, so a custom transport still works.
+   */
+  selectTopic?: (event: WidgetClientTopicEvent) => void;
   sendMessage: (event: WidgetClientCreateMessageEvent) => void;
 }
 interface CreateChatTransportOptions {
@@ -236,4 +287,4 @@ export declare const createClivlyTransport: typeof createClivlyTransport$1;
 export declare const mountChatWidget: typeof mountChatWidget$1;
 export declare const mountChatWidgetScript: typeof mountChatWidgetScript$1;
 //#endregion
-export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary };
+export type { ChatTransportConnection, ChatTransportHandlers, ChatWidgetProps, ChatWidgetTheme, ChatWidgetVisitor, CreateChatTransport, CreateChatTransportOptions, CreateLoopbackTransportOptions, CreateWebSocketTransportOptions, GetSession, GetSessionOptions, ResolvedTheme, WidgetAssistantStatusEvent, WidgetClientCreateMessageEvent, WidgetClientEvent, WidgetClientReadEvent, WidgetClientTopicEvent, WidgetConfig, WidgetContact, WidgetConversation, WidgetConversationSnapshotEvent, WidgetErrorEvent, WidgetMessage, WidgetMessageAckEvent, WidgetMessageCreatedEvent, WidgetSenderType, WidgetServerEvent, WidgetSessionPayload, WidgetSessionReadyEvent, WidgetSummary, WidgetSupport, WidgetSupportState, WidgetSupportStateEvent, WidgetSupportTopic };