@newfold/wp-module-ai-chat 1.0.0

package/src/utils/nfdAgents/greeting.js

@@ -0,0 +1,55 @@
+/**
+ * NFD Agents Greeting Utilities
+ *
+ * Utilities for detecting initial greeting messages from agents.
+ * Used to filter out system greetings that shouldn't be shown to users.
+ */
+
+/**
+ * Check if a message is an initial greeting that should be filtered out
+ *
+ * @param {string} content Message content to check
+ * @return {boolean} True if message is an initial greeting
+ */
+export const isInitialGreeting = (content) => {
+	if (!content || typeof content !== "string") {
+		return false;
+	}
+
+	const normalized = content.toLowerCase().trim();
+
+	// Common greeting patterns - more comprehensive matching
+	const greetingPatterns = [
+		/^hello!?\s+how\s+can\s+i\s+assist\s+you/i,
+		/^hi!?\s+how\s+can\s+i\s+help/i,
+		/^hello!?\s+how\s+can\s+i\s+help/i,
+		/^hi\s+there!?\s+how\s+can/i,
+		/^greetings!?\s+how\s+can/i,
+		/^how\s+can\s+i\s+assist\s+you\s+today/i,
+		/^how\s+can\s+i\s+help\s+you\s+today/i,
+		// Match "Hello! How can I assist you today? Feel free to ask me anything..."
+		/^hello!?\s+how\s+can\s+i\s+assist\s+you\s+today/i,
+		/^hello!?\s+how\s+can\s+i\s+assist\s+you.*feel\s+free/i,
+	];
+
+	// Check if message matches greeting patterns
+	const isGreeting = greetingPatterns.some((pattern) => pattern.test(normalized));
+
+	// Also check for messages that contain greeting keywords and are likely initial greetings
+	// This catches variations like "Hello! How can I assist you today? Feel free to ask me anything..."
+	const hasGreetingKeywords =
+		normalized.includes("hello") &&
+		(normalized.includes("assist") || normalized.includes("help")) &&
+		(normalized.includes("today") ||
+			normalized.includes("feel free") ||
+			normalized.includes("ask"));
+
+	// Check for very short messages that are likely greetings
+	const isShortGreeting =
+		normalized.length < 150 &&
+		((normalized.includes("hello") &&
+			(normalized.includes("assist") || normalized.includes("help"))) ||
+			(normalized.includes("hi") && normalized.includes("help")));
+
+	return isGreeting || hasGreetingKeywords || isShortGreeting;
+};

package/src/utils/nfdAgents/jwtUtils.js

@@ -0,0 +1,59 @@
+/**
+ * JWT utilities for NFD Agents.
+ *
+ * Decodes JWT payload (no signature verification) for scheduling only.
+ * Do not use for security decisions.
+ */
+
+/**
+ * Base64url-decode a string (JWT segment).
+ *
+ * @param {string} str Base64url-encoded string
+ * @return {string} Decoded string
+ */
+function base64UrlDecode(str) {
+	let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+	// Base64url often omits padding; atob requires length % 4 === 0.
+	const pad = base64.length % 4;
+	if (pad) {
+		base64 += "===".slice(0, 4 - pad);
+	}
+	try {
+		return decodeURIComponent(
+			atob(base64)
+				.split("")
+				.map((c) => "%" + ("00" + c.charCodeAt(0).toString(16)).slice(-2))
+				.join("")
+		);
+	} catch (e) {
+		return atob(base64);
+	}
+}
+
+/**
+ * Get JWT expiration timestamp in milliseconds (Unix ms).
+ * Decodes payload without verification; for scheduling only.
+ *
+ * @param {string} jwt JWT string (header.payload.signature)
+ * @return {number|null} exp * 1000, or null if missing/invalid
+ */
+export function getJwtExpirationMs(jwt) {
+	if (!jwt || typeof jwt !== "string") {
+		return null;
+	}
+	const parts = jwt.split(".");
+	if (parts.length !== 3) {
+		return null;
+	}
+	try {
+		const payloadJson = base64UrlDecode(parts[1]);
+		const payload = JSON.parse(payloadJson);
+		const exp = payload?.exp;
+		if (typeof exp !== "number" || !Number.isFinite(exp)) {
+			return null;
+		}
+		return exp * 1000;
+	} catch (e) {
+		return null;
+	}
+}

package/src/utils/nfdAgents/messageHandler.js

@@ -0,0 +1,328 @@
+/**
+ * NFD Agents WebSocket Message Handler
+ *
+ * Extracts the entire ws.onmessage protocol handling from useNfdAgentsWebSocket.
+ * Factory returns a handleMessage(data) function wired to the hook's state setters and refs.
+ */
+
+import { getStatusForEventType } from "../../constants/nfdAgents/typingStatus";
+import { isInitialGreeting } from "./greeting";
+
+/**
+ * Helper: extract and filter a message string from a WebSocket payload.
+ * Returns null when the content should be suppressed (system noise, empty, filtered greeting).
+ *
+ * @param {string|undefined} raw            Raw message string
+ * @param {boolean}          hasUserMessage Whether user has sent a message yet
+ * @return {string|null} Cleaned message or null to suppress
+ */
+const filterMessage = (raw, hasUserMessage) => {
+	const trimmed = raw?.trim();
+	if (
+		!trimmed ||
+		trimmed === "No content provided" ||
+		trimmed === "sales_requested" ||
+		trimmed.toLowerCase() === "sales_requested"
+	) {
+		return null;
+	}
+	if (!hasUserMessage && trimmed.length < 150 && isInitialGreeting(trimmed)) {
+		return null;
+	}
+	return trimmed;
+};
+
+/**
+ * Helper: clear the typing timeout ref.
+ *
+ * @param {Object} typingTimeoutRef React ref holding the timeout ID
+ */
+const clearTypingTimeout = (typingTimeoutRef) => {
+	if (typingTimeoutRef.current) {
+		clearTimeout(typingTimeoutRef.current);
+		typingTimeoutRef.current = null;
+	}
+};
+
+/**
+ * Helper: finalize typing state after content is received.
+ *
+ * @param {Object}   deps                    Subset of handler deps
+ * @param {Function} deps.setIsTyping        State setter
+ * @param {Function} deps.setStatus          State setter
+ * @param {Function} deps.setCurrentResponse State setter
+ * @param {Object}   deps.typingTimeoutRef   React ref holding the timeout ID
+ */
+const finalizeTyping = ({ setIsTyping, setStatus, setCurrentResponse, typingTimeoutRef }) => {
+	setIsTyping(false);
+	setStatus(null);
+	setCurrentResponse("");
+	clearTypingTimeout(typingTimeoutRef);
+};
+
+/**
+ * Helper: create and append an assistant message to state.
+ *
+ * @param {Function} setMessages State setter
+ * @param {string}   content     Message content
+ * @param {string}   [idSuffix]  Optional suffix for message ID
+ */
+const addAssistantMsg = (setMessages, content, idSuffix = "") => {
+	setMessages((prev) => [
+		...prev,
+		{
+			id: `msg-${Date.now()}${idSuffix}`,
+			role: "assistant",
+			type: "assistant",
+			content,
+			timestamp: new Date(),
+			animateTyping: true,
+		},
+	]);
+};
+
+/**
+ * Create a WebSocket message handler wired to the hook's state.
+ *
+ * @param {Object}   deps                    Dependencies from the hook
+ * @param {Object}   deps.isStoppedRef       Ref — skip messages after stop
+ * @param {Object}   deps.hasUserMessageRef  Ref — controls greeting filtering
+ * @param {Object}   deps.typingTimeoutRef   Ref — typing indicator timeout
+ * @param {number}   deps.typingTimeout      TYPING_TIMEOUT constant
+ * @param {Function} deps.setIsTyping        State setter
+ * @param {Function} deps.setStatus          State setter
+ * @param {Function} deps.setCurrentResponse State setter
+ * @param {Function} deps.setMessages        State setter
+ * @param {Function} deps.setConversationId  State setter
+ * @param {Function} deps.setError           State setter
+ * @param {Function} deps.saveSessionId      callback(sessionId) — persist to ref + localStorage
+ * @param {Function} deps.saveConversationId callback(id) — persist to localStorage
+ * @return {Function} handleMessage(data) — call with parsed JSON from ws.onmessage
+ */
+export function createMessageHandler(deps) {
+	const {
+		isStoppedRef,
+		hasUserMessageRef,
+		typingTimeoutRef,
+		typingTimeout,
+		setIsTyping,
+		setStatus,
+		setCurrentResponse,
+		setMessages,
+		setConversationId,
+		setError,
+		saveSessionId,
+		saveConversationId,
+	} = deps;
+
+	return function handleMessage(data) {
+		// If user has stopped generation, ignore all messages except session_established
+		if (isStoppedRef.current && data.type !== "session_established") {
+			return;
+		}
+
+		// --- session_established ---
+		if (data.type === "session_established") {
+			if (data.session_id) {
+				saveSessionId(data.session_id);
+			}
+			return;
+		}
+
+		// --- typing_start ---
+		if (data.type === "typing_start") {
+			setIsTyping(true);
+			setStatus(getStatusForEventType("typing_start"));
+			clearTypingTimeout(typingTimeoutRef);
+			return;
+		}
+
+		// --- typing_stop ---
+		if (data.type === "typing_stop") {
+			setIsTyping(false);
+			setStatus(null);
+			setCurrentResponse("");
+			clearTypingTimeout(typingTimeoutRef);
+			return;
+		}
+
+		// --- streaming_chunk / chunk ---
+		if (data.type === "streaming_chunk" || data.type === "chunk") {
+			if (isStoppedRef.current) {
+				return;
+			}
+			const content = data.content || data.chunk || data.text || "";
+			if (content) {
+				setCurrentResponse((prev) => {
+					const newContent = prev + content;
+					if (
+						!hasUserMessageRef.current &&
+						newContent.length < 100 &&
+						isInitialGreeting(newContent)
+					) {
+						return "";
+					}
+					setIsTyping(true);
+					if (typingTimeoutRef.current) {
+						clearTimeout(typingTimeoutRef.current);
+					}
+					typingTimeoutRef.current = setTimeout(() => {
+						setIsTyping(false);
+						setStatus(null);
+						typingTimeoutRef.current = null;
+					}, typingTimeout);
+					return newContent;
+				});
+			}
+			return;
+		}
+
+		// --- structured_output ---
+		if (data.type === "structured_output") {
+			const humanInputRequest = data.response_content?.content?.human_input_request;
+
+			if (humanInputRequest) {
+				const inputType = (
+					humanInputRequest.input_type ||
+					humanInputRequest.inputType ||
+					""
+				).toUpperCase();
+
+				if (inputType === "APPROVAL_REQUEST") {
+					if (data.conversation_id || data.conversationId) {
+						const newConversationId = data.conversation_id || data.conversationId;
+						setConversationId(newConversationId);
+						saveConversationId(newConversationId);
+					}
+					return;
+				}
+			}
+
+			const structuredMessage = data.message || data.response_content?.message;
+			const filtered = filterMessage(structuredMessage, hasUserMessageRef.current);
+
+			if (filtered) {
+				// Finalize any current streaming response first
+				setCurrentResponse((prev) => {
+					if (prev) {
+						addAssistantMsg(setMessages, prev, "-streaming");
+					}
+					return "";
+				});
+
+				addAssistantMsg(setMessages, filtered);
+				finalizeTyping(deps);
+			}
+			return;
+		}
+
+		// --- tool_call ---
+		if (data.type === "tool_call") {
+			setStatus(getStatusForEventType("tool_call"));
+			return;
+		}
+
+		// --- tool_result ---
+		if (data.type === "tool_result") {
+			setStatus(getStatusForEventType("tool_result"));
+			if (data.conversation_id || data.conversationId) {
+				const newConversationId = data.conversation_id || data.conversationId;
+				setConversationId(newConversationId);
+				saveConversationId(newConversationId);
+			}
+			return;
+		}
+
+		// --- message / complete ---
+		if (data.type === "message" || data.type === "complete") {
+			let hasContent = false;
+			setCurrentResponse((prev) => {
+				if (prev) {
+					const trimmedContent = prev.trim();
+					if (
+						trimmedContent === "No content provided" ||
+						trimmedContent === "sales_requested" ||
+						trimmedContent.toLowerCase() === "sales_requested"
+					) {
+						return "";
+					}
+					if (!hasUserMessageRef.current && prev.length < 150 && isInitialGreeting(prev)) {
+						return "";
+					}
+					setMessages((prevMessages) => [
+						...prevMessages,
+						{
+							id: `msg-${Date.now()}`,
+							role: "assistant",
+							type: "assistant",
+							content: prev,
+							timestamp: new Date(),
+							animateTyping: true,
+						},
+					]);
+					hasContent = true;
+				}
+				return "";
+			});
+
+			if (!hasContent) {
+				const payloadMessage = data.message || data.response_content?.message;
+				const filtered = filterMessage(payloadMessage, hasUserMessageRef.current);
+				if (filtered) {
+					addAssistantMsg(setMessages, filtered);
+					hasContent = true;
+				}
+			}
+
+			if (hasContent) {
+				finalizeTyping(deps);
+			}
+			return;
+		}
+
+		// --- handoff_accept ---
+		if (data.type === "handoff_accept") {
+			setStatus(getStatusForEventType("handoff_accept"));
+			return;
+		}
+
+		// --- handoff_request ---
+		if (data.type === "handoff_request") {
+			setStatus(getStatusForEventType("handoff_request"));
+			const messageContent = data.message || data.response_content?.message;
+			const filtered = filterMessage(messageContent, hasUserMessageRef.current);
+
+			if (!filtered) {
+				setCurrentResponse("");
+				return;
+			}
+
+			addAssistantMsg(setMessages, filtered);
+			finalizeTyping(deps);
+			return;
+		}
+
+		// --- error ---
+		if (data.type === "error") {
+			setError(data.message || data.error || "An error occurred");
+			setIsTyping(false);
+			setStatus(null);
+			setCurrentResponse("");
+			return;
+		}
+
+		// --- generic fallback (message with content) ---
+		if (data.message || data.response_content?.message) {
+			const messageContent = data.message || data.response_content?.message;
+			const filtered = filterMessage(messageContent, hasUserMessageRef.current);
+
+			if (!filtered) {
+				setCurrentResponse("");
+				return;
+			}
+
+			addAssistantMsg(setMessages, filtered);
+			finalizeTyping(deps);
+		}
+	};
+}

package/src/utils/nfdAgents/storage.js

@@ -0,0 +1,112 @@
+/**
+ * NFD Agents Storage Utilities
+ *
+ * localStorage persistence operations for chat history, conversation ID,
+ * and session ID. Extracted from useNfdAgentsWebSocket for reuse and testability.
+ */
+
+/* global localStorage */
+
+/**
+ * Check if a messages array contains at least one user message with non-empty content.
+ *
+ * @param {Array} msgs Messages array
+ * @return {boolean} True if at least one user message has non-empty content
+ */
+export const hasMeaningfulUserMessage = (msgs) =>
+	Array.isArray(msgs) &&
+	msgs.some(
+		(m) => (m.role === "user" || m.type === "user") && m.content && String(m.content).trim()
+	);
+
+/**
+ * Restore chat history, conversation ID, and session ID from localStorage.
+ *
+ * @param {string} storageKey      Key for messages
+ * @param {string} conversationKey Key for conversation ID
+ * @param {string} sessionKey      Key for session ID
+ * @return {{ messages: Array, conversationId: string|null, sessionId: string|null }} Restored messages and IDs, or empty defaults on failure or missing data
+ */
+export const restoreChat = (storageKey, conversationKey, sessionKey) => {
+	try {
+		const storedMessages = localStorage.getItem(storageKey);
+		const storedConversationId = localStorage.getItem(conversationKey);
+		const storedSessionId = localStorage.getItem(sessionKey);
+
+		if (storedMessages) {
+			const parsedMessages = JSON.parse(storedMessages);
+			if (Array.isArray(parsedMessages) && parsedMessages.length > 0) {
+				const restoredMessages = parsedMessages.map((msg) => ({
+					...msg,
+					timestamp: msg.timestamp ? new Date(msg.timestamp) : new Date(),
+					animateTyping: false,
+				}));
+				return {
+					messages: restoredMessages,
+					conversationId: storedConversationId || null,
+					sessionId: storedSessionId || null,
+				};
+			}
+		}
+	} catch (err) {
+		// eslint-disable-next-line no-console
+		console.warn("[AI Chat] Failed to restore chat history from localStorage:", err);
+	}
+	return { messages: [], conversationId: null, sessionId: null };
+};
+
+/**
+ * Persist messages to localStorage. Removes the key if messages are not meaningful.
+ *
+ * @param {string} storageKey Key for messages
+ * @param {Array}  messages   Messages array
+ */
+export const persistMessages = (storageKey, messages) => {
+	try {
+		if (hasMeaningfulUserMessage(messages)) {
+			localStorage.setItem(storageKey, JSON.stringify(messages));
+		} else {
+			localStorage.removeItem(storageKey);
+		}
+	} catch (err) {
+		// eslint-disable-next-line no-console
+		console.warn("[AI Chat] Failed to save messages to localStorage:", err);
+	}
+};
+
+/**
+ * Persist conversation ID to localStorage. Removes the key when null.
+ *
+ * @param {string}      conversationKey Key for conversation ID
+ * @param {string|null} conversationId  Conversation ID or null
+ */
+export const persistConversationId = (conversationKey, conversationId) => {
+	try {
+		if (conversationId) {
+			localStorage.setItem(conversationKey, conversationId);
+		} else {
+			localStorage.removeItem(conversationKey);
+		}
+	} catch (err) {
+		// eslint-disable-next-line no-console
+		console.warn("[AI Chat] Failed to save conversation ID to localStorage:", err);
+	}
+};
+
+/**
+ * Clear all chat-related keys from localStorage.
+ *
+ * @param {string} storageKey      Key for messages
+ * @param {string} conversationKey Key for conversation ID
+ * @param {string} sessionKey      Key for session ID
+ */
+export const clearChatStorage = (storageKey, conversationKey, sessionKey) => {
+	try {
+		localStorage.removeItem(storageKey);
+		localStorage.removeItem(conversationKey);
+		localStorage.removeItem(sessionKey);
+	} catch (err) {
+		// eslint-disable-next-line no-console
+		console.warn("[AI Chat] Failed to clear chat storage:", err);
+	}
+};