feat: Add styled error alert cards for token quota and BookStack connection failures

- Server now classifies errors before sending over SSE: bookstack_error and quota_error types
- BookStack network failures (ECONNREFUSED, ENOTFOUND, ETIMEDOUT, 5xx) surface as bookstack_error
- OpenAI quota / rate-limit errors (429, insufficient_quota) surface as quota_error
- Frontend appendErrorCard() helper renders themed alert cards in the chat stream
- Quota error: amber card with token exhausted message and IT admin contact note
- Connection error: red card with VPN hint 'Check your Zters VPN connection'
- Generic error: red card fallback
- All error cards adapt to dark and light mode via scoped CSS overrides

Author: Osaron

chatbot/public/app.js

@@ -115,6 +115,44 @@ function appendMessage(role, content, html = false) {
     return div;
 }
 
+// Styled error alert cards
+function appendErrorCard(type) {
+    if (welcomeScreen.style.display !== 'none') {
+        welcomeScreen.style.display = 'none';
+    }
+
+    let variant, icon, title, desc;
+
+    if (type === 'quota_error') {
+        variant = 'quota';
+        icon    = '⚠️';
+        title   = 'AI Token Quota Reached';
+        desc    = 'The OpenAI token quota for this account has been exhausted. Please contact your Zters IT administrator to top up the API credits.';
+    } else if (type === 'bookstack_error') {
+        variant = 'connection';
+        icon    = '🔌';
+        title   = 'Cannot Connect to BookStack';
+        desc    = 'The assistant is unable to reach the Zters knowledge base. Please check your <strong>Zters VPN connection</strong> and try again.';
+    } else {
+        variant = 'generic';
+        icon    = '❌';
+        title   = 'Something went wrong';
+        desc    = 'An unexpected error occurred. Please try again or contact Zters IT support if the problem persists.';
+    }
+
+    const card = document.createElement('div');
+    card.className = `error-card ${variant}`;
+    card.innerHTML = `
+        <span class="error-icon">${icon}</span>
+        <div class="error-body">
+            <span class="error-title">${title}</span>
+            <span class="error-desc">${desc}</span>
+        </div>
+    `;
+    messagesWrapper.appendChild(card);
+    scrollToBottom();
+}
+
 function updateStatus(text) {
     let indicator = document.getElementById('current-status');
     if (!indicator) {
@@ -281,10 +319,15 @@ async function handleChatRequest(message, isSystemCommand = false) {
                             botMsgDiv.innerHTML = marked.parse(fullResponse);
                             scrollToBottom();
                         }
+                        else if (data.type === 'quota_error' || data.type === 'bookstack_error') {
+                            removeStatus();
+                            botMsgDiv.remove(); // remove empty bot placeholder
+                            appendErrorCard(data.type);
+                        }
                         else if (data.type === 'error') {
                             removeStatus();
-                            fullResponse += `\n\n*Error: ${data.content}*`;
-                            botMsgDiv.innerHTML = marked.parse(fullResponse);
+                            botMsgDiv.remove();
+                            appendErrorCard('error');
                         }
                         else if (data.type === 'done') {
                             removeStatus();
@@ -305,7 +348,8 @@ async function handleChatRequest(message, isSystemCommand = false) {
         }
     } catch (error) {
         removeStatus();
-        botMsgDiv.innerHTML = `<span style="color:red">Connection error: ${error.message}</span>`;
+        botMsgDiv.remove();
+        appendErrorCard('bookstack_error');
     } finally {
         sendBtn.disabled = false;
         input.focus();

chatbot/public/styles.css

@@ -800,3 +800,91 @@ a:hover { text-decoration: underline; }
     transition: all 0.2s;
 }
 .view-sources-btn:hover { background: rgba(255,255,255,0.05); color: var(--text-primary); }
+
+/* ── Error Alert Cards ─────────────────────────────────────────────── */
+.error-card {
+    align-self: flex-start;
+    width: 100%;
+    max-width: 680px;
+    border-radius: 10px;
+    padding: 14px 18px;
+    margin-bottom: 20px;
+    display: flex;
+    gap: 14px;
+    align-items: flex-start;
+    animation: fadeIn 0.3s ease;
+    border: 1px solid transparent;
+}
+
+.error-card .error-icon {
+    font-size: 1.3rem;
+    flex-shrink: 0;
+    margin-top: 1px;
+}
+
+.error-card .error-body {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+}
+
+.error-card .error-title {
+    font-weight: 600;
+    font-size: 0.95rem;
+}
+
+.error-card .error-desc {
+    font-size: 0.875rem;
+    line-height: 1.5;
+    opacity: 0.9;
+}
+
+/* — Quota / token limit — amber */
+.error-card.quota {
+    background: rgba(251, 191, 36, 0.12);
+    border-color: rgba(251, 191, 36, 0.4);
+    border-left: 4px solid #f59e0b;
+    color: #fbbf24;
+}
+.error-card.quota .error-title { color: #fbbf24; }
+.error-card.quota .error-desc  { color: #fde68a; }
+
+/* — BookStack connection — red */
+.error-card.connection {
+    background: rgba(239, 68, 68, 0.12);
+    border-color: rgba(239, 68, 68, 0.35);
+    border-left: 4px solid #ef4444;
+    color: #f87171;
+}
+.error-card.connection .error-title { color: #f87171; }
+.error-card.connection .error-desc  { color: #fca5a5; }
+
+/* — Generic error — same red palette */
+.error-card.generic {
+    background: rgba(239, 68, 68, 0.12);
+    border-color: rgba(239, 68, 68, 0.35);
+    border-left: 4px solid #ef4444;
+    color: #f87171;
+}
+.error-card.generic .error-title { color: #f87171; }
+.error-card.generic .error-desc  { color: #fca5a5; }
+
+/* Light-mode overrides for error cards */
+body.light-theme .error-card.quota {
+    background: #fffbeb;
+    border-color: #fcd34d;
+    color: #92400e;
+}
+body.light-theme .error-card.quota .error-title { color: #92400e; }
+body.light-theme .error-card.quota .error-desc  { color: #b45309; }
+
+body.light-theme .error-card.connection,
+body.light-theme .error-card.generic {
+    background: #fef2f2;
+    border-color: #fca5a5;
+    color: #991b1b;
+}
+body.light-theme .error-card.connection .error-title,
+body.light-theme .error-card.generic .error-title { color: #991b1b; }
+body.light-theme .error-card.connection .error-desc,
+body.light-theme .error-card.generic .error-desc  { color: #b91c1c; }

chatbot/server.js

@@ -39,6 +39,12 @@ async function searchBookStack(query, count = 10) {
     return res.data.data || [];
   } catch (err) {
     console.error('BookStack search error:', err.message);
+    // Surface connection failures with a typed error so the caller can report them
+    if (err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT' || (err.response && err.response.status >= 500)) {
+      const e = new Error('Cannot reach the BookStack server');
+      e.type = 'bookstack_error';
+      throw e;
+    }
     return [];
   }
 }
@@ -318,7 +324,29 @@ ${contextBlock}`;
     res.end();
   } catch (err) {
     console.error('Chat error:', err);
-    res.write(`data: ${JSON.stringify({ type: 'error', content: err.message })}\n\n`);
+
+    // Classify the error for the frontend
+    let errorType = 'error';
+    let errorMsg  = err.message;
+
+    if (err.type === 'bookstack_error') {
+      errorType = 'bookstack_error';
+      errorMsg  = 'Cannot reach the BookStack server.';
+    } else if (
+      err?.status === 429 ||
+      err?.error?.type === 'insufficient_quota' ||
+      (err.message && (err.message.includes('quota') || err.message.includes('rate limit') || err.message.includes('insufficient_quota') || err.message.includes('429')))
+    ) {
+      errorType = 'quota_error';
+      errorMsg  = 'OpenAI token quota exceeded.';
+    } else if (
+      err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' || err.code === 'ETIMEDOUT'
+    ) {
+      errorType = 'bookstack_error';
+      errorMsg  = 'Cannot reach the BookStack server.';
+    }
+
+    res.write(`data: ${JSON.stringify({ type: errorType, content: errorMsg })}\n\n`);
     res.end();
   }
 });