@veluai/velu 0.2.25 → 0.2.27

package/runtime/velu-ui/lib/docs-assistant.js

@@ -1,273 +1,273 @@
-/**
- * docs-assistant — runtime client for the published docs site's "Ask AI",
- * talking to the backend's PUBLIC docs-AI-assistant API:
- *
- *   GET  /api/v1/public/ai-assistant/bootstrap                    (visitor cookie + tenant)
- *   POST /api/v1/public/ai-assistant/messages                     ({ message, conversation_id })
- *   GET  /api/v1/public/ai-assistant/conversations/{id}/events    (SSE; ?token=…)
- *   POST|DELETE /api/v1/public/ai-assistant/messages/{id}/feedback ({ rating })
- *
- * `createDocsAssistant({ apiBase, host })` returns `{ ask, sendFeedback }`,
- * shaped to drop straight into <Chatbot ask onFeedback>. `ask` is an async
- * generator yielding the AskEvent shape Chatbot expects.
- *
- * Contract notes (from the backend):
- *  - bootstrap sets an **httponly visitor cookie**, so every call uses
- *    `credentials: 'include'`. Cross-origin therefore needs CORS w/ credentials
- *    AND a cross-site-capable cookie (SameSite=None) — today the cookie is
- *    SameSite=Lax, so the API must be same-site with the docs (proxied under the
- *    docs domain) until the backend relaxes it. See the plan's open questions.
- *  - tenant is resolved from the `X-Velu-Site-Host` header (falls back to Origin).
- *  - POST /messages returns immediately; the answer is generated in the
- *    background and arrives as a SINGLE `assistant.completed` SSE event with the
- *    full content + citations (NOT token-by-token). So `ask` yields one content
- *    event when the answer is ready (the panel shows its "thinking" state until).
- */
-
-const trimSlash = (s) => String(s || '').replace(/\/+$/, '');
-
-function siteHost(explicit) {
-  if (explicit) return explicit;
-  return typeof window !== 'undefined' ? window.location.host : '';
-}
-
-// Parse one raw SSE record ("id: N\nevent: x\ndata: {…}") into { event, data, seq }.
-function parseSseRecord(raw) {
-  let event = 'message';
-  let seq = null;
-  const dataLines = [];
-  for (const line of raw.split('\n')) {
-    if (line.startsWith('event:')) event = line.slice(6).trim();
-    else if (line.startsWith('id:')) {
-      const n = Number(line.slice(3).trim());
-      if (Number.isFinite(n)) seq = n;
-    } else if (line.startsWith('data:')) dataLines.push(line.slice(5).replace(/^ /, ''));
-  }
-  let data = null;
-  if (dataLines.length) {
-    try { data = JSON.parse(dataLines.join('\n')); } catch { data = null; }
-  }
-  return { event, data, seq };
-}
-
-// Backend citation → the Chatbot's Source shape.
-function mapCitations(cits) {
-  if (!Array.isArray(cits)) return undefined;
-  return cits.map((c, i) => ({
-    num: c.num ?? c.index ?? i + 1,
-    title: c.title,
-    path: c.route_path ?? c.path,
-    url: c.url,
-  }));
-}
-
-// Renumber cited sources 1,2,3… in order of first appearance and rewrite the
-// [n] markers in the text to match. The backend keeps the raw RAG ranks (the
-// LLM may cite [1] and [5]); this makes them sequential and drops uncited ones.
-function renumberCitations(content, citations) {
-  const text = content || '';
-  const order = [];
-  const re = /\[(\d+)\]/g;
-  let m;
-  while ((m = re.exec(text)) !== null) {
-    const n = Number(m[1]);
-    if (!order.includes(n)) order.push(n);
-  }
-  if (!order.length) return { content: text, citations: [] };
-  const remap = new Map(order.map((old, i) => [old, i + 1]));
-  const newContent = text.replace(/\[(\d+)\]/g, (full, d) =>
-    remap.has(Number(d)) ? `[${remap.get(Number(d))}]` : full,
-  );
-  const byNum = new Map((citations || []).map((c) => [c.num, c]));
-  const newCitations = order
-    .map((old) => byNum.get(old))
-    .filter(Boolean)
-    .map((c, i) => ({ ...c, num: i + 1 }));
-  return { content: newContent, citations: newCitations };
-}
-
-export function createDocsAssistant({ apiBase, host } = {}) {
-  const base = trimSlash(apiBase);
-  if (!base) return null;
-  const root = `${base}/api/v1/public/ai-assistant`;
-  let bootstrapped = false;
-  // Whether the docs owner's plan + credit balance allow Ask-AI right now.
-  // Set from /bootstrap; the host UI hides the widget when false. Fail-open
-  // (stays true) if bootstrap can't be reached so a transient error doesn't
-  // wrongly hide a working assistant.
-  let askEnabled = true;
-  // Highest event seq seen per conversation. The events endpoint replays history
-  // after `after_seq`; without this a reused (multi-turn) conversation replays
-  // from 0 and the first (old) assistant.completed is returned for every
-  // follow-up turn — i.e. the answer never updates after the first message.
-  const lastSeqByConv = new Map();
-
-  const headers = (extra) => ({
-    'X-Velu-Site-Host': siteHost(host),
-    ...extra,
-  });
-
-  async function bootstrap() {
-    if (bootstrapped) return;
-    // Sets the httponly visitor cookie used by every subsequent call, and tells
-    // us whether Ask-AI is currently enabled for this site (plan + credits).
-    const res = await fetch(`${root}/bootstrap`, {
-      method: 'GET',
-      credentials: 'include',
-      headers: headers(),
-    });
-    try {
-      const data = await res.json();
-      if (typeof data?.ask_ai_enabled === 'boolean') askEnabled = data.ask_ai_enabled;
-    } catch {
-      /* keep fail-open default */
-    }
-    bootstrapped = true;
-  }
-
-  // Resolve whether the widget should be shown (runs bootstrap once). Returns
-  // true on any error so a transient failure never hides a working assistant.
-  async function isEnabled() {
-    try {
-      await bootstrap();
-    } catch {
-      return true;
-    }
-    return askEnabled;
-  }
-
-  // Async generator: yields { conversationId } early, then one
-  // { delta, citations, messageId, conversationId } when the answer is ready.
-  async function* ask(prompt, { conversationId, signal } = {}) {
-    await bootstrap();
-
-    const res = await fetch(`${root}/messages`, {
-      method: 'POST',
-      credentials: 'include',
-      headers: headers({ 'Content-Type': 'application/json' }),
-      body: JSON.stringify({ message: prompt, conversation_id: conversationId ?? null }),
-      signal,
-    });
-    if (!res.ok) throw new Error(`ask-ai: messages ${res.status}`);
-    const { conversation_id: convId, conversation_token: token } = await res.json();
-    yield { conversationId: convId };
-
-    // Manual fetch-stream SSE parse (not EventSource): supports credentials,
-    // the X-Velu-Site-Host header, and AbortController cancellation.
-    const afterSeq = lastSeqByConv.get(convId) ?? 0;
-    const evRes = await fetch(
-      `${root}/conversations/${convId}/events?after_seq=${afterSeq}&token=${encodeURIComponent(token)}`,
-      { credentials: 'include', headers: headers({ Accept: 'text/event-stream' }), signal },
-    );
-    if (!evRes.ok || !evRes.body) throw new Error(`ask-ai: stream ${evRes.status}`);
-
-    const reader = evRes.body.getReader();
-    const decoder = new TextDecoder();
-    let buf = '';
-    try {
-      while (true) {
-        const { value, done } = await reader.read();
-        if (done) break;
-        buf += decoder.decode(value, { stream: true });
-        let sep;
-        while ((sep = buf.indexOf('\n\n')) !== -1) {
-          const { event, data, seq } = parseSseRecord(buf.slice(0, sep));
-          buf = buf.slice(sep + 2);
-          if (seq != null) {
-            lastSeqByConv.set(convId, Math.max(lastSeqByConv.get(convId) ?? 0, seq));
-          }
-          if (event === 'assistant.completed') {
-            const m = data?.message || {};
-            const renum = renumberCitations(m.content || '', mapCitations(m.citations));
-            yield {
-              delta: renum.content,
-              citations: renum.citations,
-              messageId: m.id,
-              conversationId: convId,
-            };
-            return; // answer delivered — done
-          }
-          if (event === 'assistant.error') {
-            throw new Error(data?.error || 'ask-ai: generation failed');
-          }
-          // message.created (echoed user turn) and ping are ignored.
-        }
-      }
-    } finally {
-      try {
-        await reader.cancel();
-      } catch {
-        /* already closed */
-      }
-    }
-  }
-
-  // rating: 'up' | 'down' to set, null to retract.
-  async function sendFeedback(messageId, rating) {
-    if (messageId == null) return;
-    const url = `${root}/messages/${messageId}/feedback`;
-    if (rating == null) {
-      await fetch(url, { method: 'DELETE', credentials: 'include', headers: headers() });
-      return;
-    }
-    await fetch(url, {
-      method: 'POST',
-      credentials: 'include',
-      headers: headers({ 'Content-Type': 'application/json' }),
-      body: JSON.stringify({ rating }),
-    });
-  }
-
-  // The visitor's recent conversations on this site (the history panel).
-  // Returns [{ conversationId, token, title, updatedAt }], newest first.
-  async function listConversations() {
-    await bootstrap();
-    const res = await fetch(`${root}/conversations`, {
-      credentials: 'include',
-      headers: headers(),
-    });
-    if (!res.ok) throw new Error(`ask-ai: conversations ${res.status}`);
-    const { conversations } = await res.json();
-    return (conversations || []).map((c) => ({
-      conversationId: c.conversation_id,
-      token: c.conversation_token,
-      title: c.title,
-      lastSeq: c.last_seq,
-      updatedAt: c.updated_at,
-    }));
-  }
-
-  // Load a past conversation's messages (to resume it in the panel).
-  // Returns { conversationId, messages: [{ role, content, citations,
-  // messageId }] } with citations already renumbered to the Chatbot's Source
-  // shape. Also records the conversation's last seq so a follow-up `ask` on
-  // it streams from the right offset instead of replaying history.
-  async function loadConversation({ conversationId, token, lastSeq }) {
-    const res = await fetch(`${root}/conversations/${conversationId}`, {
-      credentials: 'include',
-      headers: headers({ Authorization: `Bearer ${token}` }),
-    });
-    if (!res.ok) throw new Error(`ask-ai: conversation ${res.status}`);
-    const data = await res.json();
-    let maxSeq = lastSeq ?? 0;
-    const messages = (data.messages || []).map((m) => {
-      if (m.seq != null) maxSeq = Math.max(maxSeq, m.seq);
-      if (m.role !== 'assistant') {
-        return { role: m.role, content: m.content, messageId: m.id };
-      }
-      const renum = renumberCitations(m.content || '', mapCitations(m.citations));
-      return {
-        role: 'assistant',
-        content: renum.content,
-        citations: renum.citations,
-        messageId: m.id,
-      };
-    });
-    lastSeqByConv.set(conversationId, Math.max(lastSeqByConv.get(conversationId) ?? 0, maxSeq));
-    return { conversationId, messages };
-  }
-
-  return { ask, sendFeedback, listConversations, loadConversation, isEnabled };
-}
-
-export default createDocsAssistant;
+/**
+ * docs-assistant — runtime client for the published docs site's "Ask AI",
+ * talking to the backend's PUBLIC docs-AI-assistant API:
+ *
+ *   GET  /api/v1/public/ai-assistant/bootstrap                    (visitor cookie + tenant)
+ *   POST /api/v1/public/ai-assistant/messages                     ({ message, conversation_id })
+ *   GET  /api/v1/public/ai-assistant/conversations/{id}/events    (SSE; ?token=…)
+ *   POST|DELETE /api/v1/public/ai-assistant/messages/{id}/feedback ({ rating })
+ *
+ * `createDocsAssistant({ apiBase, host })` returns `{ ask, sendFeedback }`,
+ * shaped to drop straight into <Chatbot ask onFeedback>. `ask` is an async
+ * generator yielding the AskEvent shape Chatbot expects.
+ *
+ * Contract notes (from the backend):
+ *  - bootstrap sets an **httponly visitor cookie**, so every call uses
+ *    `credentials: 'include'`. Cross-origin therefore needs CORS w/ credentials
+ *    AND a cross-site-capable cookie (SameSite=None) — today the cookie is
+ *    SameSite=Lax, so the API must be same-site with the docs (proxied under the
+ *    docs domain) until the backend relaxes it. See the plan's open questions.
+ *  - tenant is resolved from the `X-Velu-Site-Host` header (falls back to Origin).
+ *  - POST /messages returns immediately; the answer is generated in the
+ *    background and arrives as a SINGLE `assistant.completed` SSE event with the
+ *    full content + citations (NOT token-by-token). So `ask` yields one content
+ *    event when the answer is ready (the panel shows its "thinking" state until).
+ */
+
+const trimSlash = (s) => String(s || '').replace(/\/+$/, '');
+
+function siteHost(explicit) {
+  if (explicit) return explicit;
+  return typeof window !== 'undefined' ? window.location.host : '';
+}
+
+// Parse one raw SSE record ("id: N\nevent: x\ndata: {…}") into { event, data, seq }.
+function parseSseRecord(raw) {
+  let event = 'message';
+  let seq = null;
+  const dataLines = [];
+  for (const line of raw.split('\n')) {
+    if (line.startsWith('event:')) event = line.slice(6).trim();
+    else if (line.startsWith('id:')) {
+      const n = Number(line.slice(3).trim());
+      if (Number.isFinite(n)) seq = n;
+    } else if (line.startsWith('data:')) dataLines.push(line.slice(5).replace(/^ /, ''));
+  }
+  let data = null;
+  if (dataLines.length) {
+    try { data = JSON.parse(dataLines.join('\n')); } catch { data = null; }
+  }
+  return { event, data, seq };
+}
+
+// Backend citation → the Chatbot's Source shape.
+function mapCitations(cits) {
+  if (!Array.isArray(cits)) return undefined;
+  return cits.map((c, i) => ({
+    num: c.num ?? c.index ?? i + 1,
+    title: c.title,
+    path: c.route_path ?? c.path,
+    url: c.url,
+  }));
+}
+
+// Renumber cited sources 1,2,3… in order of first appearance and rewrite the
+// [n] markers in the text to match. The backend keeps the raw RAG ranks (the
+// LLM may cite [1] and [5]); this makes them sequential and drops uncited ones.
+function renumberCitations(content, citations) {
+  const text = content || '';
+  const order = [];
+  const re = /\[(\d+)\]/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const n = Number(m[1]);
+    if (!order.includes(n)) order.push(n);
+  }
+  if (!order.length) return { content: text, citations: [] };
+  const remap = new Map(order.map((old, i) => [old, i + 1]));
+  const newContent = text.replace(/\[(\d+)\]/g, (full, d) =>
+    remap.has(Number(d)) ? `[${remap.get(Number(d))}]` : full,
+  );
+  const byNum = new Map((citations || []).map((c) => [c.num, c]));
+  const newCitations = order
+    .map((old) => byNum.get(old))
+    .filter(Boolean)
+    .map((c, i) => ({ ...c, num: i + 1 }));
+  return { content: newContent, citations: newCitations };
+}
+
+export function createDocsAssistant({ apiBase, host } = {}) {
+  const base = trimSlash(apiBase);
+  if (!base) return null;
+  const root = `${base}/api/v1/public/ai-assistant`;
+  let bootstrapped = false;
+  // Whether the docs owner's plan + credit balance allow Ask-AI right now.
+  // Set from /bootstrap; the host UI hides the widget when false. Fail-open
+  // (stays true) if bootstrap can't be reached so a transient error doesn't
+  // wrongly hide a working assistant.
+  let askEnabled = true;
+  // Highest event seq seen per conversation. The events endpoint replays history
+  // after `after_seq`; without this a reused (multi-turn) conversation replays
+  // from 0 and the first (old) assistant.completed is returned for every
+  // follow-up turn — i.e. the answer never updates after the first message.
+  const lastSeqByConv = new Map();
+
+  const headers = (extra) => ({
+    'X-Velu-Site-Host': siteHost(host),
+    ...extra,
+  });
+
+  async function bootstrap() {
+    if (bootstrapped) return;
+    // Sets the httponly visitor cookie used by every subsequent call, and tells
+    // us whether Ask-AI is currently enabled for this site (plan + credits).
+    const res = await fetch(`${root}/bootstrap`, {
+      method: 'GET',
+      credentials: 'include',
+      headers: headers(),
+    });
+    try {
+      const data = await res.json();
+      if (typeof data?.ask_ai_enabled === 'boolean') askEnabled = data.ask_ai_enabled;
+    } catch {
+      /* keep fail-open default */
+    }
+    bootstrapped = true;
+  }
+
+  // Resolve whether the widget should be shown (runs bootstrap once). Returns
+  // true on any error so a transient failure never hides a working assistant.
+  async function isEnabled() {
+    try {
+      await bootstrap();
+    } catch {
+      return true;
+    }
+    return askEnabled;
+  }
+
+  // Async generator: yields { conversationId } early, then one
+  // { delta, citations, messageId, conversationId } when the answer is ready.
+  async function* ask(prompt, { conversationId, signal } = {}) {
+    await bootstrap();
+
+    const res = await fetch(`${root}/messages`, {
+      method: 'POST',
+      credentials: 'include',
+      headers: headers({ 'Content-Type': 'application/json' }),
+      body: JSON.stringify({ message: prompt, conversation_id: conversationId ?? null }),
+      signal,
+    });
+    if (!res.ok) throw new Error(`ask-ai: messages ${res.status}`);
+    const { conversation_id: convId, conversation_token: token } = await res.json();
+    yield { conversationId: convId };
+
+    // Manual fetch-stream SSE parse (not EventSource): supports credentials,
+    // the X-Velu-Site-Host header, and AbortController cancellation.
+    const afterSeq = lastSeqByConv.get(convId) ?? 0;
+    const evRes = await fetch(
+      `${root}/conversations/${convId}/events?after_seq=${afterSeq}&token=${encodeURIComponent(token)}`,
+      { credentials: 'include', headers: headers({ Accept: 'text/event-stream' }), signal },
+    );
+    if (!evRes.ok || !evRes.body) throw new Error(`ask-ai: stream ${evRes.status}`);
+
+    const reader = evRes.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        let sep;
+        while ((sep = buf.indexOf('\n\n')) !== -1) {
+          const { event, data, seq } = parseSseRecord(buf.slice(0, sep));
+          buf = buf.slice(sep + 2);
+          if (seq != null) {
+            lastSeqByConv.set(convId, Math.max(lastSeqByConv.get(convId) ?? 0, seq));
+          }
+          if (event === 'assistant.completed') {
+            const m = data?.message || {};
+            const renum = renumberCitations(m.content || '', mapCitations(m.citations));
+            yield {
+              delta: renum.content,
+              citations: renum.citations,
+              messageId: m.id,
+              conversationId: convId,
+            };
+            return; // answer delivered — done
+          }
+          if (event === 'assistant.error') {
+            throw new Error(data?.error || 'ask-ai: generation failed');
+          }
+          // message.created (echoed user turn) and ping are ignored.
+        }
+      }
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+
+  // rating: 'up' | 'down' to set, null to retract.
+  async function sendFeedback(messageId, rating) {
+    if (messageId == null) return;
+    const url = `${root}/messages/${messageId}/feedback`;
+    if (rating == null) {
+      await fetch(url, { method: 'DELETE', credentials: 'include', headers: headers() });
+      return;
+    }
+    await fetch(url, {
+      method: 'POST',
+      credentials: 'include',
+      headers: headers({ 'Content-Type': 'application/json' }),
+      body: JSON.stringify({ rating }),
+    });
+  }
+
+  // The visitor's recent conversations on this site (the history panel).
+  // Returns [{ conversationId, token, title, updatedAt }], newest first.
+  async function listConversations() {
+    await bootstrap();
+    const res = await fetch(`${root}/conversations`, {
+      credentials: 'include',
+      headers: headers(),
+    });
+    if (!res.ok) throw new Error(`ask-ai: conversations ${res.status}`);
+    const { conversations } = await res.json();
+    return (conversations || []).map((c) => ({
+      conversationId: c.conversation_id,
+      token: c.conversation_token,
+      title: c.title,
+      lastSeq: c.last_seq,
+      updatedAt: c.updated_at,
+    }));
+  }
+
+  // Load a past conversation's messages (to resume it in the panel).
+  // Returns { conversationId, messages: [{ role, content, citations,
+  // messageId }] } with citations already renumbered to the Chatbot's Source
+  // shape. Also records the conversation's last seq so a follow-up `ask` on
+  // it streams from the right offset instead of replaying history.
+  async function loadConversation({ conversationId, token, lastSeq }) {
+    const res = await fetch(`${root}/conversations/${conversationId}`, {
+      credentials: 'include',
+      headers: headers({ Authorization: `Bearer ${token}` }),
+    });
+    if (!res.ok) throw new Error(`ask-ai: conversation ${res.status}`);
+    const data = await res.json();
+    let maxSeq = lastSeq ?? 0;
+    const messages = (data.messages || []).map((m) => {
+      if (m.seq != null) maxSeq = Math.max(maxSeq, m.seq);
+      if (m.role !== 'assistant') {
+        return { role: m.role, content: m.content, messageId: m.id };
+      }
+      const renum = renumberCitations(m.content || '', mapCitations(m.citations));
+      return {
+        role: 'assistant',
+        content: renum.content,
+        citations: renum.citations,
+        messageId: m.id,
+      };
+    });
+    lastSeqByConv.set(conversationId, Math.max(lastSeqByConv.get(conversationId) ?? 0, maxSeq));
+    return { conversationId, messages };
+  }
+
+  return { ask, sendFeedback, listConversations, loadConversation, isEnabled };
+}
+
+export default createDocsAssistant;