@clivly/chat-widget 0.14.1 → 0.15.0

package/README.md

@@ -289,6 +289,7 @@ Important fields include:
 - `contact`
 - `messages`
 - optional `socketUrl`
+- optional `support` (see [Support assistant](#support-assistant))
 
 When `socketUrl` is present, the widget prefers it over reconstructing the
 socket URL from a client-side template.
@@ -326,6 +327,26 @@ shows a short note that the team has been
 notified, and that the reply will also go to the visitor's email when one is
 known. A failed send doesn't start the clock, because nobody was notified about it.
 
+## Support assistant
+
+When the widget has guided support turned on in Clivly (**Settings → Chat
+widget → Support**), the session payload carries `support` — the mode, the
+conversation's state, and the topics to offer (ids and labels only; answers stay
+on the server). The widget then:
+
+- shows the server-written greeting, and every automated or AI message, with an
+  **Automated** / **AI assistant** badge (`message.automation` says which);
+- offers the topics as buttons under the transcript while `support.state` is
+  `"automated"`, alongside the message box, and hides them after a handoff or a
+  teammate's reply (`support.state` server event);
+- shows *The AI assistant is looking for an answer…* while an
+  `assistant.status` event says `thinking`.
+
+A topic click is sent as `{ type: "topic.select", id, topicId }`. A **custom
+transport** opts in with the optional `ChatTransportConnection.selectTopic()`;
+without it, a click is sent as the topic's label in an ordinary message. A
+payload without `support` renders exactly as before.
+
 ## Build outputs
 
 The package currently produces:
@@ -373,7 +394,7 @@ unreachable Clivly into a JSON `502` instead of a thrown `fetch`.
 | --- | --- | --- |
 | Widget mounts but every session is `403` | The origin is not in the widget record's allowlist. It is **exact-match**: `https://example.com` does not cover `https://www.example.com` | Add every embedding origin, with scheme, under **Settings → Chat widget** |
 | A brand-new widget refuses everything | An empty origin list permits nothing | Add at least one origin |
-| `503 widget_not_configured` | The Clivly server has no `CLIVLY_WIDGET_TOKEN_SECRET` | Only relevant when self-hosting — set it, or set `CLIVLY_MASTER_KEY` |
+| `503 widget_not_configured` | The Clivly server cannot sign widget sessions | A Clivly-side configuration problem, not something in your app — contact Clivly support |
 | Session request returns an opaque `400` | The route was hand-written and omits `origin` from the **body**, or rejects `visitorToken: null` | Use `createChatSessionHandler` from `clivly/sdk` |
 | `404` on the session request | `sessionUrl` does not match where you mounted the route | `clivly add widget` writes `/api/clivly/widget/session` — match it, or set `sessionUrl` to your path |
 | Bundle throws on `node:fs` / `node:child_process` | Something imported the `clivly` package root | Import the handler from `clivly/sdk` |

package/dist/browser-mount.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);
@@ -372,6 +379,47 @@ const WIDGET_STYLES = `
   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;
@@ -468,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;
@@ -490,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", {
@@ -540,6 +622,7 @@ 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();
 	}
@@ -593,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);
@@ -601,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 ?? ""
@@ -631,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: () => {
@@ -681,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) {
@@ -713,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,
@@ -785,8 +945,10 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 						})]
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						"aria-label": "Conversation",
 						className: "clivly-chat-widget__body",
 						ref: listRef,
+						role: "log",
 						children: [
 							error ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 								className: "clivly-chat-widget__error",
@@ -797,10 +959,17 @@ function ChatWidget({ className, createTransport, defaultVisitor, getSession, in
 								hasSession: Boolean(session),
 								messages
 							}),
-							session && showWaitingNotice ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-								className: "clivly-chat-widget__notice",
-								role: "status",
-								children: waitingNoticeText(session.contact?.email)
+							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
 						]
 					}),
@@ -822,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", {
@@ -948,6 +1117,10 @@ function createWebSocketTransport({ createSocket = (url, protocols) => new WebSo
 			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/browser-mount.d.cts

@@ -34,11 +34,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;
@@ -46,6 +65,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;
@@ -65,6 +86,12 @@ interface WidgetClientCreateMessageEvent {
   id: string;
   type: "message.create";
 }
+/** The visitor picked a guided topic (see `ChatTransportConnection.selectTopic`). */
+interface WidgetClientTopicEvent {
+  id: string;
+  topicId: string;
+  type: "topic.select";
+}
 interface WidgetSessionReadyEvent {
   conversationId: string;
   type: "session.ready";
@@ -83,11 +110,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 {
@@ -104,6 +140,11 @@ interface ChatTransportConnection {
    * 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 {

package/dist/browser-mount.d.mts

@@ -34,11 +34,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;
@@ -46,6 +65,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;
@@ -65,6 +86,12 @@ interface WidgetClientCreateMessageEvent {
   id: string;
   type: "message.create";
 }
+/** The visitor picked a guided topic (see `ChatTransportConnection.selectTopic`). */
+interface WidgetClientTopicEvent {
+  id: string;
+  topicId: string;
+  type: "topic.select";
+}
 interface WidgetSessionReadyEvent {
   conversationId: string;
   type: "session.ready";
@@ -83,11 +110,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 {
@@ -104,6 +140,11 @@ interface ChatTransportConnection {
    * 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 {