sagedesk 1.0.0 → 2.1.0

package/dist/react/index.d.ts

@@ -2,6 +2,7 @@ import React from 'react';
 
 type SageDeskModel = 'all-MiniLM-L6-v2' | 'bge-small-en-v1-5' | 'paraphrase-multilingual-MiniLM-L12-v2' | 'all-mpnet-base-v2';
 type Theme = 'classic' | 'light' | 'dark';
+type SageDeskMode = 'local' | 'llm';
 interface AgentConfig {
     name: string;
     model?: SageDeskModel;
@@ -13,7 +14,6 @@ interface AgentConfig {
     position?: 'bottom-right' | 'bottom-left';
     avatarUrl?: string;
     contactUrl?: string;
-    poweredBy?: boolean;
     suggestedChips?: string[];
 }
 interface SearchConfig {
@@ -21,25 +21,34 @@ interface SearchConfig {
     topK?: number;
 }
 interface SageDeskConfig {
-    indexUrl: string;
+    mode?: SageDeskMode;
+    indexUrl?: string;
+    endpoint?: string;
     agent: AgentConfig;
     search?: SearchConfig;
 }
+type FallbackReason = 'auth-error' | 'quota-exceeded' | 'timeout' | 'api-error' | 'malformed-response';
 interface ChatMessage {
     id: string;
     role: 'user' | 'bot';
     text: string;
     isFallback?: boolean;
+    fallbackReason?: FallbackReason;
     timestamp: Date;
 }
 type EngineStatus = 'idle' | 'loading-index' | 'loading-model' | 'ready' | 'error-index' | 'error-model' | 'degraded';
 
 interface SageDeskWidgetProps {
-    indexUrl: string;
+    /** Operating mode. 'local' (default) runs entirely in the browser via WASM. 'llm' posts to the consumer's own backend. */
+    mode?: SageDeskMode;
+    /** URL to the pre-built vector index. Required in local mode. */
+    indexUrl?: string;
+    /** Consumer's backend endpoint that accepts POST { query }. Required in llm mode. */
+    endpoint?: string;
     agent: SageDeskConfig['agent'];
     search?: SageDeskConfig['search'];
 }
-declare function SageDeskWidget({ indexUrl, agent, search }: SageDeskWidgetProps): React.ReactPortal | null;
+declare function SageDeskWidget({ mode, indexUrl, endpoint, agent, search }: SageDeskWidgetProps): React.ReactPortal | null;
 
 interface State {
     messages: ChatMessage[];
@@ -58,4 +67,4 @@ interface UseSageDeskReturn {
 }
 declare function useSageDesk(config: SageDeskConfig): UseSageDeskReturn;
 
-export { type AgentConfig, type ChatMessage, type SageDeskConfig, SageDeskWidget, type SageDeskWidgetProps, type SearchConfig, type UseSageDeskReturn, useSageDesk };
+export { type AgentConfig, type ChatMessage, type SageDeskConfig, type SageDeskMode, SageDeskWidget, type SageDeskWidgetProps, type SearchConfig, type UseSageDeskReturn, useSageDesk };

package/dist/react/index.js

@@ -94,17 +94,33 @@ function dotProduct(a, b) {
   for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
   return dot;
 }
+function insertSorted(arr, item, maxLen) {
+  arr.push(item);
+  let i = arr.length - 1;
+  while (i > 0 && arr[i - 1].score < arr[i].score) {
+    const tmp = arr[i - 1];
+    arr[i - 1] = arr[i];
+    arr[i] = tmp;
+    i--;
+  }
+  if (arr.length > maxLen) arr.pop();
+}
 function search(queryVector, index, topK = 3, minScore = 0.42) {
   const results = [];
   for (const chunk of index) {
     const score = dotProduct(queryVector, chunk.vector384);
     if (score < minScore) continue;
     if (results.length < topK) {
-      results.push({ chunk, score });
-      results.sort((a, b) => b.score - a.score);
+      insertSorted(results, { chunk, score }, topK);
     } else if (score > results[topK - 1].score) {
       results[topK - 1] = { chunk, score };
-      results.sort((a, b) => b.score - a.score);
+      let i = topK - 1;
+      while (i > 0 && results[i - 1].score < results[i].score) {
+        const tmp = results[i - 1];
+        results[i - 1] = results[i];
+        results[i] = tmp;
+        i--;
+      }
     }
   }
   return results;
@@ -115,15 +131,23 @@ function keywordSearch(query, index, topK = 3) {
   const results = [];
   for (const chunk of index) {
     const chunkLower = chunk.textLower || chunk.text.toLowerCase();
-    const matchCount = terms.filter((t) => chunkLower.includes(t)).length;
+    let matchCount = 0;
+    for (const t of terms) {
+      if (chunkLower.includes(t)) matchCount++;
+    }
     const score = matchCount / terms.length;
     if (score <= 0) continue;
     if (results.length < topK) {
-      results.push({ chunk, score });
-      results.sort((a, b) => b.score - a.score);
+      insertSorted(results, { chunk, score }, topK);
     } else if (score > results[topK - 1].score) {
       results[topK - 1] = { chunk, score };
-      results.sort((a, b) => b.score - a.score);
+      let i = topK - 1;
+      while (i > 0 && results[i - 1].score < results[i].score) {
+        const tmp = results[i - 1];
+        results[i - 1] = results[i];
+        results[i] = tmp;
+        i--;
+      }
     }
   }
   return results;
@@ -226,6 +250,17 @@ function getFallback(config) {
 }
 
 // src/react/useSageDesk.ts
+function logFallbackWarning(reason) {
+  if (!reason) return;
+  const messages = {
+    "auth-error": "[sagedesk] Support service authentication failed. Showing relevant knowledge instead.",
+    "quota-exceeded": "[sagedesk] Support service quota exhausted. Showing relevant knowledge instead.",
+    "timeout": "[sagedesk] Support service took too long to respond. Showing relevant knowledge instead.",
+    "api-error": "[sagedesk] Support service error. Showing relevant knowledge instead.",
+    "malformed-response": "[sagedesk] Support service returned invalid response. Showing relevant knowledge instead."
+  };
+  console.warn(messages[reason] || "[sagedesk] Support service unavailable. Showing relevant knowledge instead.");
+}
 var initialState = {
   messages: [],
   isOpen: false,
@@ -278,6 +313,11 @@ function useSageDesk(config) {
   const startEngine = useCallback(async () => {
     if (engineStartedRef.current) return;
     engineStartedRef.current = true;
+    if (config.mode === "llm") {
+      setChips(config.agent.suggestedChips ?? []);
+      dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "ready" } });
+      return;
+    }
     dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "loading-index" } });
     try {
       indexRef.current = await fetchIndex(config.indexUrl);
@@ -304,7 +344,7 @@ function useSageDesk(config) {
       embedderRef.current = new EmbedderRuntime();
       dispatch({ type: "SET_ENGINE_STATUS", payload: { status: "degraded" } });
     }
-  }, [config.indexUrl, config.agent.suggestedChips, addMessage]);
+  }, [config.mode, config.indexUrl, config.agent.suggestedChips, addMessage]);
   const greetingShownRef = useRef(false);
   const open = useCallback(() => {
     dispatch({ type: "OPEN" });
@@ -347,8 +387,37 @@ function useSageDesk(config) {
       }
       let botText;
       let isFallback = false;
-      let mode = "keyword";
-      if (!indexRef.current) {
+      let fallbackReason;
+      let retrievalMode = "keyword";
+      if (config.mode === "llm") {
+        if (!config.endpoint) {
+          console.warn('[sagedesk] LLM mode requires an "endpoint" prop.');
+          botText = getFallback(config.agent);
+          isFallback = true;
+        } else {
+          try {
+            const res = await fetch(config.endpoint, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ query: trimmed })
+            });
+            if (!res.ok) throw new Error(`HTTP ${res.status}`);
+            const data = await res.json();
+            if (data.isFallback || !data.answer) {
+              fallbackReason = data.fallbackReason;
+              logFallbackWarning(fallbackReason);
+              botText = getFallback(config.agent);
+              isFallback = true;
+            } else {
+              botText = data.answer;
+            }
+          } catch (err) {
+            console.warn("[sagedesk] Support service unavailable. Using cached knowledge instead.");
+            botText = getFallback(config.agent);
+            isFallback = true;
+          }
+        }
+      } else if (!indexRef.current) {
         botText = getFallback(config.agent);
         isFallback = true;
       } else {
@@ -359,7 +428,7 @@ function useSageDesk(config) {
             embedderRef.current,
             config.search
           );
-          mode = res.mode;
+          retrievalMode = res.mode;
           if (res.results.length > 0) {
             botText = buildAnswer(res.results);
           } else {
@@ -372,11 +441,13 @@ function useSageDesk(config) {
           isFallback = true;
         }
       }
-      const elapsed = Date.now() - typingStart;
-      const delayBase = mode === "keyword" || isFallback ? 800 : 3e3;
-      const minTypingMs = delayBase + Math.random() * 2e3;
-      const remaining = minTypingMs - elapsed;
-      if (remaining > 0) await new Promise((r) => setTimeout(r, remaining));
+      if (config.mode !== "llm") {
+        const elapsed = Date.now() - typingStart;
+        const delayBase = retrievalMode === "keyword" || isFallback ? 800 : 3e3;
+        const minTypingMs = delayBase + Math.random() * 2e3;
+        const remaining = minTypingMs - elapsed;
+        if (remaining > 0) await new Promise((r) => setTimeout(r, remaining));
+      }
       dispatch({ type: "SET_TYPING", payload: false });
       addMessage({ role: "bot", text: botText, isFallback });
     },
@@ -399,6 +470,51 @@ function useSageDesk(config) {
   return { state, chips: activeChips, open, close, submit };
 }
 
+// src/react/markdownUtils.ts
+import { marked } from "marked";
+import DOMPurify from "dompurify";
+marked.setOptions({
+  breaks: true,
+  gfm: true,
+  pedantic: false
+});
+var PURIFY_CONFIG = {
+  ALLOWED_TAGS: [
+    "p",
+    "br",
+    "strong",
+    "em",
+    "u",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "ul",
+    "ol",
+    "li",
+    "blockquote",
+    "code",
+    "pre",
+    "a",
+    "hr"
+  ],
+  ALLOWED_ATTR: ["href", "title", "target", "rel"],
+  ALLOW_DATA_ATTR: false
+};
+DOMPurify.addHook("afterSanitizeAttributes", (node) => {
+  if (node.tagName.toLowerCase() === "a") {
+    node.setAttribute("target", "_blank");
+    node.setAttribute("rel", "noopener noreferrer");
+  }
+});
+function parseMarkdown(markdown) {
+  const html = marked.parse(markdown);
+  const sanitized = DOMPurify.sanitize(html, PURIFY_CONFIG);
+  return sanitized;
+}
+
 // src/react/SageDeskWidget.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 var STYLE_ID = "sagedesk-widget-styles";
@@ -428,6 +544,28 @@ var SHARED = `
   }
   .sd-r-scrollable::-webkit-scrollbar { display: none !important; }
   .sd-r-scrollable > * { flex-shrink: 0 !important; }
+  .sd-r-markdown h1, .sd-r-markdown h2, .sd-r-markdown h3, .sd-r-markdown h4, .sd-r-markdown h5, .sd-r-markdown h6 {
+    margin: 12px 0 8px 0 !important; font-weight: 600 !important; line-height: 1.3 !important;
+  }
+  .sd-r-markdown h1 { font-size: 1.3em !important; }
+  .sd-r-markdown h2 { font-size: 1.2em !important; }
+  .sd-r-markdown h3 { font-size: 1.1em !important; }
+  .sd-r-markdown h4, .sd-r-markdown h5, .sd-r-markdown h6 { font-size: 1em !important; }
+  .sd-r-markdown strong { font-weight: 600 !important; }
+  .sd-r-markdown em { font-style: italic !important; }
+  .sd-r-markdown u { text-decoration: underline !important; }
+  .sd-r-markdown ul, .sd-r-markdown ol { margin: 8px 0 !important; padding-left: 20px !important; }
+  .sd-r-markdown li { margin: 4px 0 !important; }
+  .sd-r-markdown blockquote { margin: 8px 0 !important; padding-left: 12px !important; border-left: 3px solid currentColor !important; opacity: 0.8 !important; }
+  .sd-r-markdown code { font-family: 'Monaco', 'Courier New', monospace !important; font-size: 0.9em !important; padding: 2px 4px !important; background: rgba(0,0,0,0.05) !important; border-radius: 3px !important; }
+  .sd-r-markdown pre { background: rgba(0,0,0,0.05) !important; padding: 8px 10px !important; border-radius: 6px !important; overflow-x: auto !important; margin: 8px 0 !important; }
+  .sd-r-markdown pre code { background: none !important; padding: 0 !important; }
+  .sd-r-markdown hr { border: none !important; border-top: 1px solid currentColor !important; opacity: 0.3 !important; margin: 10px 0 !important; }
+  .sd-r-markdown a { text-decoration: underline !important; opacity: 0.9 !important; }
+  .sd-r-markdown a:hover { opacity: 1 !important; }
+  .sd-r-markdown p { margin: 6px 0 !important; }
+  .sd-r-markdown > *:first-child { margin-top: 0 !important; }
+  .sd-r-markdown > *:last-child { margin-bottom: 0 !important; }
   @media (max-width: 420px) {
     .sd-r-panel {
       bottom: 0 !important; right: 0 !important; left: 0 !important;
@@ -514,7 +652,7 @@ var PoweredBy = ({ dark = false }) => /* @__PURE__ */ jsxs("div", { style: {
     {
       href: "https://github.com/mzeeshanwahid/sagedesk",
       target: "_blank",
-      rel: "noopener noreferrer",
+      rel: "noopener",
       style: {
         color: dark ? "rgba(255,255,255,0.7)" : "#5a5a64",
         fontWeight: 500,
@@ -526,6 +664,7 @@ var PoweredBy = ({ dark = false }) => /* @__PURE__ */ jsxs("div", { style: {
 ] });
 function ClassicMessageBubble({ msg, accent }) {
   const isBot = msg.role === "bot";
+  const renderedHtml = isBot ? parseMarkdown(msg.text) : msg.text;
   return /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", alignItems: isBot ? "flex-start" : "flex-end", gap: "4px" }, children: [
     msg.isFallback && /* @__PURE__ */ jsx("p", { style: { fontSize: "11px", fontWeight: 500, color: "#9b9aa3", margin: 0, padding: "0 4px", fontFamily: "inherit" }, children: "Not sure about that one" }),
     /* @__PURE__ */ jsx("div", { style: {
@@ -538,10 +677,9 @@ function ClassicMessageBubble({ msg, accent }) {
       color: isBot ? "#1a1a2e" : "#fff",
       border: isBot ? "1px solid rgba(20,20,40,0.06)" : "none",
       boxShadow: isBot ? "0 1px 2px rgba(20,20,40,0.04)" : `0 6px 16px -6px color-mix(in oklab, ${accent} 60%, transparent)`,
-      whiteSpace: "pre-wrap",
       wordBreak: "break-word",
       fontFamily: "inherit"
-    }, children: msg.text }),
+    }, className: "sd-r-markdown", children: isBot ? /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: renderedHtml } }) : /* @__PURE__ */ jsx("div", { style: { whiteSpace: "pre-wrap" }, children: msg.text }) }),
     /* @__PURE__ */ jsx("span", { style: {
       fontSize: "11px",
       color: "#a8a8b0",
@@ -571,6 +709,7 @@ function ClassicTypingIndicator() {
 }
 function LightMessageBubble({ msg, accent, agentName }) {
   const isBot = msg.role === "bot";
+  const renderedHtml = isBot ? parseMarkdown(msg.text) : msg.text;
   if (isBot) {
     return /* @__PURE__ */ jsxs("div", { style: { display: "flex", gap: "10px" }, children: [
       /* @__PURE__ */ jsx("div", { style: {
@@ -587,7 +726,7 @@ function LightMessageBubble({ msg, accent, agentName }) {
           /* @__PURE__ */ jsx("span", { style: { fontSize: "11px", color: "#a8a89e", fontVariantNumeric: "tabular-nums", fontFamily: "inherit" }, children: "just now" })
         ] }),
         msg.isFallback && /* @__PURE__ */ jsx("p", { style: { fontSize: "11px", color: "#9b9aa3", margin: "0 0 4px", fontFamily: "inherit" }, children: "Not sure about that one" }),
-        /* @__PURE__ */ jsx("div", { style: { fontSize: "14px", lineHeight: 1.55, color: "#2a2a36", fontFamily: "inherit", whiteSpace: "pre-wrap", wordBreak: "break-word" }, children: msg.text })
+        /* @__PURE__ */ jsx("div", { style: { fontSize: "14px", lineHeight: 1.55, color: "#2a2a36", fontFamily: "inherit", wordBreak: "break-word" }, className: "sd-r-markdown", children: /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: renderedHtml } }) })
       ] })
     ] });
   }
@@ -635,6 +774,7 @@ function LightTypingIndicator({ accent }) {
 }
 function DarkMessageBubble({ msg, accent }) {
   const isBot = msg.role === "bot";
+  const renderedHtml = isBot ? parseMarkdown(msg.text) : msg.text;
   return /* @__PURE__ */ jsxs("div", { style: {
     maxWidth: "85%",
     padding: "12px 14px",
@@ -646,12 +786,11 @@ function DarkMessageBubble({ msg, accent }) {
     color: isBot ? "rgba(255,255,255,0.92)" : "#fff",
     alignSelf: isBot ? "flex-start" : "flex-end",
     boxShadow: isBot ? "none" : `0 8px 20px -8px color-mix(in oklab, ${accent} 70%, transparent)`,
-    whiteSpace: "pre-wrap",
     wordBreak: "break-word",
     fontFamily: "inherit"
-  }, children: [
+  }, className: isBot ? "sd-r-markdown" : "", children: [
     msg.isFallback && /* @__PURE__ */ jsx("span", { style: { fontSize: "11px", color: "rgba(255,255,255,0.5)", display: "block", marginBottom: "4px" }, children: "Not sure about that one" }),
-    msg.text
+    isBot ? /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: renderedHtml } }) : /* @__PURE__ */ jsx("div", { style: { whiteSpace: "pre-wrap" }, children: msg.text })
   ] });
 }
 function DarkTypingIndicator() {
@@ -1271,16 +1410,22 @@ function renderDark(p) {
     ] })
   ] });
 }
-function SageDeskWidget({ indexUrl, agent, search: search2 }) {
-  if (!indexUrl) {
+function SageDeskWidget({ mode, indexUrl, endpoint, agent, search: search2 }) {
+  const resolvedMode = mode ?? "local";
+  if (!agent?.name) {
+    throw new Error('[sagedesk] Required prop "agent.name" is missing.');
+  }
+  if (resolvedMode === "local" && !indexUrl) {
     throw new Error(
-      '[sagedesk] Required prop "indexUrl" is missing. Run `npx sagedesk build` and pass the output path, e.g. indexUrl="/support-index.json".'
+      '[sagedesk] Required prop "indexUrl" is missing for local mode. Run `npx sagedesk build` and pass the output path, e.g. indexUrl="/support-index.json".'
     );
   }
-  if (!agent?.name) {
-    throw new Error('[sagedesk] Required prop "agent.name" is missing.');
+  if (resolvedMode === "llm" && !endpoint) {
+    throw new Error(
+      '[sagedesk] Required prop "endpoint" is missing for llm mode. Provide your backend route, e.g. endpoint="/api/sagedesk".'
+    );
   }
-  const config = { indexUrl, agent, search: search2 };
+  const config = { mode: resolvedMode, indexUrl, endpoint, agent, search: search2 };
   const { state, chips, open, close, submit } = useSageDesk(config);
   const theme = agent.theme ?? "classic";
   const accent = agent.accentColor ?? "#534AB7";
@@ -1293,7 +1438,7 @@ function SageDeskWidget({ indexUrl, agent, search: search2 }) {
   const triggerRef = useRef2(null);
   const [mounted, setMounted] = useState2(false);
   useEffect2(() => {
-    if (!indexUrl.startsWith("/") && !indexUrl.startsWith("http")) {
+    if (resolvedMode === "local" && indexUrl && !indexUrl.startsWith("/") && !indexUrl.startsWith("http")) {
       console.warn(
         `[sagedesk] indexUrl "${indexUrl}" looks like a relative path. It should start with "/" so it resolves correctly from any page.`
       );
@@ -1335,7 +1480,7 @@ function SageDeskWidget({ indexUrl, agent, search: search2 }) {
     [handleSubmit]
   );
   if (!mounted || typeof document === "undefined") return null;
-  const showPoweredBy = agent.poweredBy !== false;
+  const showPoweredBy = true;
   const showChips = chips.length > 0;
   const panelClass = isClosing ? "sd-r-closing" : state.isOpen ? "sd-r-opening" : "";
   const props = {