Embedding a Web Chat Widget

export async function askStream({ api, question, conversationId, token, signal, onEvent }) {
  const headers = { "Content-Type": "application/json", Accept: "text/event-stream" };
  if (token) headers.Authorization = `Bearer ${token}`;

  const res = await fetch(api, {
    method: "POST",
    headers,
    body: JSON.stringify({ question, conversationId }),
    signal,
  });
  if (!res.ok) {
    // Problem details (application/problem+json): show a stable message, never the raw body.
    const problem = await res.json().catch(() => ({}));
    throw Object.assign(new Error(problem.type ?? `http-${res.status}`), { status: res.status });
  }
  if (!res.body) throw new Error("streaming-unsupported");

  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = "";
  for (;;) {
    const { value, done } = await reader.read();
    if (done) break;
    buffer += value;
    let end;
    // A blank line ends an event; accept both LF LF and CRLF CRLF (lone CR is not handled).
    while ((end = buffer.search(/\r?\n\r?\n/)) >= 0) {
      const block = buffer.slice(0, end);
      buffer = buffer.slice(end).replace(/^\r?\n\r?\n/, "");
      let event = "message";
      const data = [];
      for (const line of block.split(/\r?\n/)) {
        if (line.startsWith(":")) continue;                       // comment / keep-alive
        const i = line.indexOf(":");
        const field = i < 0 ? line : line.slice(0, i);
        const val = i < 0 ? "" : line.slice(i + 1).replace(/^ /, "");
        if (field === "event") event = val;
        else if (field === "data") data.push(val);
      }
      if (data.length) onEvent(event, JSON.parse(data.join("\n")));
    }
  }
}

(() => {
  const script = document.currentScript;                 // read synchronously; null for modules
  const cfg = {
    api: script.dataset.api,                             // https://api.example.org/v1/ask
    tokenUrl: script.dataset.tokenUrl,                   // same-origin endpoint of the host, optional
    title: script.dataset.title ?? "Docs assistant",
    linkHosts: (script.dataset.linkHosts ?? "").split(",").filter(Boolean), // allowed citation hosts
  };

  const sheet = new CSSStyleSheet();
  sheet.replaceSync(`
    :host { all: initial; font: 16px/1.4 system-ui, sans-serif; color-scheme: light dark;
            --da-accent: #1a56db; --da-bg: Canvas; --da-fg: CanvasText; --da-radius: 12px; }
    * { box-sizing: border-box; }
    .launcher { position: fixed; right: 16px; bottom: 16px; min-width: 48px; min-height: 48px; border-radius: 24px;
                border: 0; background: var(--da-accent); color: #fff; font: inherit; padding: 0 16px; cursor: pointer; }
    .panel { position: fixed; right: 16px; bottom: 80px; width: min(380px, calc(100vw - 32px)); max-height: 70vh;
             display: flex; flex-direction: column; background: var(--da-bg); color: var(--da-fg);
             border: 1px solid GrayText; border-radius: var(--da-radius); }
    .panel[hidden] { display: none; }
    h2 { font-size: 1rem; margin: 0; padding: 12px; border-bottom: 1px solid GrayText; }
    ol.transcript { list-style: none; margin: 0; padding: 12px; overflow: auto; flex: 1; }
    li.msg { margin: 0 0 12px; white-space: pre-wrap; overflow-wrap: anywhere; }
    li.user { text-align: right; }
    form { display: flex; gap: 8px; padding: 12px; border-top: 1px solid GrayText; }
    input { flex: 1; min-height: 44px; font: inherit; padding: 0 8px; }
    button { min-height: 44px; font: inherit; }
    :focus-visible { outline: 3px solid var(--da-accent); outline-offset: 2px; }
    .sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
    @media (prefers-reduced-motion: no-preference) { ol.transcript { scroll-behavior: smooth; } }
  `);

  const h = (tag, props = {}, ...kids) => {
    const el = document.createElement(tag);
    for (const [k, v] of Object.entries(props)) {
      if (k === "onclick" || k === "onsubmit" || k === "onkeydown") el.addEventListener(k.slice(2), v);
      else el.setAttribute(k, v);
    }
    el.append(...kids);                                  // strings become Text nodes, never HTML
    return el;
  };

  class DocsAssistant extends HTMLElement {
    #abort; #conversationId;

    connectedCallback() {
      if (this.shadowRoot) return;
      const root = this.attachShadow({ mode: "open" });
      root.adoptedStyleSheets = [sheet];

      this.launcher = h("button", { class: "launcher", type: "button", "aria-expanded": "false",
        "aria-controls": "panel" }, cfg.title);
      this.status = h("div", { class: "sr-only", role: "status" });           // polite live region
      this.transcript = h("ol", { class: "transcript", "aria-label": "Conversation" });
      this.input = h("input", { type: "text", name: "q", maxlength: "4000", autocomplete: "off",
        "aria-label": "Your question" });
      this.stop = h("button", { type: "button", hidden: "", onclick: () => this.#abort?.abort() }, "Stop");
      const form = h("form", { onsubmit: (e) => { e.preventDefault(); this.#send(); } },
        this.input, h("button", { type: "submit" }, "Send"), this.stop);
      this.panel = h("div", { id: "panel", role: "dialog", "aria-labelledby": "title", hidden: "",
        class: "panel", onkeydown: (e) => { if (e.key === "Escape") this.#toggle(false); } },
        h("h2", { id: "title" }, cfg.title), this.transcript, form);

      this.launcher.addEventListener("click", () => this.#toggle(this.panel.hidden));
      root.append(this.launcher, this.panel, this.status);
    }

    disconnectedCallback() { this.#abort?.abort(); }

    #toggle(open) {
      this.panel.hidden = !open;
      this.launcher.setAttribute("aria-expanded", String(open));
      (open ? this.input : this.launcher).focus();       // move focus in on open, back out on close
    }

    async #token() {
      if (!cfg.tokenUrl) return null;
      const res = await fetch(cfg.tokenUrl, { credentials: "same-origin" });   // host's own origin
      return res.ok ? (await res.json()).token : null;
    }

    async #send() {
      const question = this.input.value.trim();
      if (!question || this.#abort) return;
      this.input.value = "";
      this.transcript.append(h("li", { class: "msg user" }, question));
      const answer = h("li", { class: "msg bot" });
      this.transcript.append(answer);
      let text = "";
      this.#abort = new AbortController();
      this.stop.hidden = false;
      this.status.textContent = "Searching the documentation";
      try {
        await askStream({
          api: cfg.api, question, conversationId: this.#conversationId, token: await this.#token(),
          signal: this.#abort.signal,
          onEvent: (event, p) => {
            if (event === "token") { text += p.text; answer.textContent = text; }
            else if (event === "citations") answer.replaceChildren(...renderAnswer(text, p, cfg.linkHosts));
            else if (event === "done") this.#conversationId = p.conversationId;
            else if (event === "error") throw new Error(p.type);
          },
        });
        this.status.textContent = text;                  // announce the finished answer once
      } catch (err) {
        if (err.name !== "AbortError") answer.textContent = "Sorry, the assistant is unavailable. Please try again.";
        this.status.textContent = err.name === "AbortError" ? "Stopped" : "The assistant is unavailable";
      } finally {
        this.#abort = undefined;
        this.stop.hidden = true;
        this.transcript.scrollTop = this.transcript.scrollHeight;
      }
    }
  }

  if (!customElements.get("docs-assistant")) customElements.define("docs-assistant", DocsAssistant);
  document.body.append(document.createElement("docs-assistant"));
})();

<script src="https://widget.example.org/1.4.0/docs-assistant.js"
        integrity="sha384-REPLACE_WITH_THE_PUBLISHED_HASH" crossorigin="anonymous" defer
        data-api="https://api.example.org/v1/ask"
        data-token-url="/assistant/token"
        data-title="Ask the docs"
        data-link-hosts="docs.example.org"></script>

function safeUrl(raw, linkHosts = []) {
  try {
    const url = new URL(raw, location.href);
    const okProtocol = url.protocol === "https:";               // http: only if you really need it
    const okHost = linkHosts.length === 0 || linkHosts.includes(url.hostname);
    return okProtocol && okHost ? url.href : null;
  } catch {
    return null;
  }
}

function renderAnswer(text, citations, linkHosts) {
  const byMarker = new Map(citations.map((c) => [String(c.marker), c]));
  const nodes = [];
  const list = h("ol", { class: "sources", "aria-label": "Sources" });

  for (const part of text.split(/(\[\d+\])/)) {
    const marker = /^\[(\d+)\]$/.exec(part)?.[1];
    if (!marker || !byMarker.has(marker)) { nodes.push(document.createTextNode(part)); continue; }
    const target = h("li", { value: marker, tabindex: "-1" });
    const c = byMarker.get(marker);
    const href = safeUrl(c.url, linkHosts);
    target.append(href
      ? h("a", { href, target: "_blank", rel: "noopener noreferrer" }, c.title)
      : document.createTextNode(c.title));
    if (c.quote) target.append(h("blockquote", {}, c.quote));
    list.append(target);
    nodes.push(h("sup", {}, h("button", {
      type: "button", "aria-label": `Source ${marker}: ${c.title}`,
      onclick: () => target.focus(),                       // focus the source item inside the same shadow tree
    }, marker)));
  }
  return list.children.length ? [...nodes, list] : nodes;
}

import { useCallback, useEffect, useReducer, useRef } from "react";
import { askStream } from "./docs-assistant-client.js";

function reducer(state, action) {
  switch (action.type) {
    case "ask":       return { ...state, busy: true, messages: [...state.messages,
                        { role: "user", text: action.text }, { role: "assistant", text: "", citations: [] }] };
    case "token":     return { ...state, messages: state.messages.map((m, i) =>
                        i === state.messages.length - 1 ? { ...m, text: m.text + action.text } : m) };
    case "citations": return { ...state, messages: state.messages.map((m, i) =>
                        i === state.messages.length - 1 ? { ...m, citations: action.citations } : m) };
    case "done":      return { ...state, busy: false, conversationId: action.conversationId };
    case "error":     return { ...state, busy: false, error: action.message };
    default:          return state;
  }
}

export function useDocsAssistant({ api, getToken }) {
  const [state, dispatch] = useReducer(reducer, { messages: [], busy: false });
  const controller = useRef(null);

  useEffect(() => () => controller.current?.abort(), []);       // cancel on unmount

  const send = useCallback(async (question) => {
    controller.current = new AbortController();
    dispatch({ type: "ask", text: question });
    try {
      await askStream({
        api, question, conversationId: state.conversationId, token: await getToken?.(),
        signal: controller.current.signal,
        onEvent: (event, p) => {
          if (event === "token") dispatch({ type: "token", text: p.text });
          else if (event === "citations") dispatch({ type: "citations", citations: p });
          else if (event === "done") dispatch({ type: "done", conversationId: p.conversationId });
          else if (event === "error") throw new Error(p.type);
        },
      });
    } catch (e) {
      if (e.name !== "AbortError") dispatch({ type: "error", message: "The assistant is unavailable." });
      else dispatch({ type: "done", conversationId: state.conversationId });
    }
  }, [api, getToken, state.conversationId]);

  return { ...state, send, stop: () => controller.current?.abort() };
}

export function DocsAssistant({ api, getToken, linkHosts = [] }) {
  const { messages, busy, error, send, stop } = useDocsAssistant({ api, getToken });
  return (
    <section aria-labelledby="da-title">
      <h2 id="da-title">Ask the docs</h2>
      <ol aria-label="Conversation">
        {messages.map((m, i) => (
          <li key={i}>
            {m.text /* JSX escapes text: no HTML is ever parsed */}
            {m.citations?.map((c) => (
              <a key={c.marker} href={safeUrl(c.url, linkHosts)} rel="noopener noreferrer" target="_blank">{c.title}</a>
            ))}
          </li>
        ))}
      </ol>
      {error && <p role="alert">{error}</p>}
      <form onSubmit={(e) => { e.preventDefault(); const q = new FormData(e.currentTarget).get("q"); e.currentTarget.reset(); send(String(q)); }}>
        <input name="q" aria-label="Your question" />
        <button type="submit" disabled={busy}>Send</button>
        {busy && <button type="button" onClick={stop}>Stop</button>}
      </form>
    </section>
  );
}

import { createRoot } from "react-dom/client";

class ReactDocsAssistant extends HTMLElement {
  #root;
  connectedCallback() {
    const shadow = this.attachShadow({ mode: "open" });
    const style = document.createElement("style");
    style.textContent = WIDGET_CSS;                  // a bundler's global CSS would land in <head>, outside the shadow tree
    const mount = document.createElement("div");
    shadow.append(style, mount);
    this.#root = createRoot(mount);
    const linkHosts = (this.getAttribute("link-hosts") ?? "").split(",").filter(Boolean);
    this.#root.render(<DocsAssistant api={this.getAttribute("api")} linkHosts={linkHosts} />);
  }
  disconnectedCallback() { this.#root?.unmount(); }
}
customElements.define("react-docs-assistant", ReactDocsAssistant);

import { onScopeDispose, ref } from "vue";
import { askStream } from "./docs-assistant-client.js";

export function useDocsAssistant({ api, getToken }) {
  const messages = ref([]);
  const busy = ref(false);
  let conversationId;
  let controller;

  async function send(question) {
    controller = new AbortController();
    busy.value = true;
    messages.value.push({ role: "user", text: question });
    const answer = { role: "assistant", text: "", citations: [] };
    messages.value.push(answer);
    const reactive = messages.value.at(-1);                  // the reactive proxy of the object just pushed
    try {
      await askStream({
        api, question, conversationId, token: await getToken?.(), signal: controller.signal,
        onEvent: (event, p) => {
          if (event === "token") reactive.text += p.text;
          else if (event === "citations") reactive.citations = p;
          else if (event === "done") conversationId = p.conversationId;
          else if (event === "error") throw new Error(p.type);
        },
      });
    } catch (e) {
      if (e.name !== "AbortError") reactive.text = "The assistant is unavailable.";
    } finally {
      busy.value = false;
    }
  }

  onScopeDispose(() => controller?.abort());                 // cancel when the component unmounts
  return { messages, busy, send, stop: () => controller?.abort() };
}

<script setup>
import { ref } from "vue";
import { useDocsAssistant } from "./useDocsAssistant.js";
import { safeUrl } from "./safe-url.js";

const props = defineProps({ api: String, linkHosts: { type: String, default: "" } });
const linkHosts = props.linkHosts.split(",").filter(Boolean);   // allowed citation hosts, as in the script-tag widget
const { messages, busy, send, stop } = useDocsAssistant({ api: props.api });
const question = ref("");
function submit() { const q = question.value.trim(); if (q) { question.value = ""; send(q); } }
</script>

<template>
  <section aria-labelledby="da-title">
    <h2 id="da-title">Ask the docs</h2>
    <ol aria-label="Conversation">
      <li v-for="(m, i) in messages" :key="i">
        {{ m.text }}
        <a v-for="c in m.citations" :key="c.marker" :href="safeUrl(c.url, linkHosts)" target="_blank" rel="noopener noreferrer">{{ c.title }}</a>
      </li>
    </ol>
    <form @submit.prevent="submit">
      <input v-model="question" aria-label="Your question" />
      <button type="submit" :disabled="busy">Send</button>
      <button v-if="busy" type="button" @click="stop">Stop</button>
    </form>
  </section>
</template>

<style>
section { font: 16px/1.4 system-ui, sans-serif; }
</style>

import { defineCustomElement } from "vue";
import DocsAssistant from "./DocsAssistant.ce.vue";

customElements.define("vue-docs-assistant", defineCustomElement(DocsAssistant));

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://www.example.com", "https://docs.example.org"],   # loaded from configuration
    allow_methods=["POST"],
    allow_headers=["Authorization", "Content-Type", "Idempotency-Key"],
    expose_headers=["X-Trace-Id"],
    max_age=3600,
)

@Bean
SecurityFilterChain api(HttpSecurity http) throws Exception {
    return http
        .cors(Customizer.withDefaults())                       // uses the CorsConfigurationSource bean below
        .authorizeHttpRequests(a -> a.anyRequest().authenticated())
        .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
        .build();
}

@Bean
CorsConfigurationSource corsConfigurationSource(WidgetProperties props) {
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowedOrigins(props.allowedOrigins());            // exact origins from configuration
    config.setAllowedMethods(List.of("POST", "OPTIONS"));
    config.setAllowedHeaders(List.of("Authorization", "Content-Type", "Idempotency-Key"));
    config.setExposedHeaders(List.of("X-Trace-Id"));
    config.setMaxAge(Duration.ofHours(1));
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/v1/**", config);
    return source;
}

<iframe src="https://chat.example.org/embed?site=docs" title="Ask the docs"
        sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
        allow="clipboard-write" loading="lazy"
        style="border:0; width:380px; height:560px"></iframe>

<!-- chat.example.org response header: only these sites may frame it -->
<!-- Content-Security-Policy: frame-ancestors https://www.example.com https://docs.example.org -->