@dogsbay/plugin-ask 0.2.0-beta.101

package/dist/index.js

@@ -0,0 +1,73 @@
+/**
+ * `@dogsbay/plugin-ask` — adds a floating "Ask AI" widget to every page of a
+ * Dogsbay docs site. The widget POSTs the user's question to a shared
+ * dogsbay-ask proxy (a Cloudflare Worker over AI Search) and streams back a
+ * grounded answer. No build-time content transform — purely a client module +
+ * styles + a build-time→client config bridge.
+ *
+ * Usage:
+ *
+ *   # dogsbay.config.yml
+ *   plugins:
+ *     - name: "@dogsbay/plugin-ask"
+ *       options:
+ *         endpoint: "https://dogsbay-ask.<subdomain>.workers.dev"
+ *         site: "openshift-docs-dogsbay"
+ *
+ * The `endpoint` + `site` are required; everything else is presentation.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseOptions } from "./schema.js";
+// __dirname is `dist/` for the published package. Client JS is built next to
+// this file; styles ship un-built at the package root under `src/`.
+const PLUGIN_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(PLUGIN_DIR, "..");
+const CLIENT_PATH = path.join(PLUGIN_DIR, "client.js");
+const STYLES_PATH = path.join(PACKAGE_ROOT, "src", "styles.css");
+// Server-rendered docked-panel shell. Ships un-built under `src/` (like the
+// stylesheet) and is wired into DocsLayout's `right-rail` slot via the
+// `componentWrappers()` hook when placement allows a rail.
+const RAIL_WRAPPER_PATH = path.join(PACKAGE_ROOT, "src", "RightRailAsk.astro");
+export default function ask(input) {
+    const opts = parseOptions(input);
+    return {
+        name: "@dogsbay/plugin-ask",
+        clientModules() {
+            return [CLIENT_PATH];
+        },
+        styles() {
+            return [STYLES_PATH];
+        },
+        componentWrappers() {
+            // Contribute the docked panel to DocsLayout's `right-rail` slot unless
+            // the site forced the floating-only widget. In "floating" mode the rail
+            // stays an inert passthrough and the client renders the modal instead.
+            if (opts.placement === "floating")
+                return {};
+            return { RightRail: RAIL_WRAPPER_PATH };
+        },
+        defineClientConfig(ctx) {
+            // JSON-safe runtime config exposed at
+            // virtual:dogsbay-plugin-config/@dogsbay/plugin-ask
+            return {
+                endpoint: opts.endpoint,
+                site: opts.site,
+                mode: opts.mode,
+                buttonLabel: opts.buttonLabel,
+                title: opts.title,
+                placeholder: opts.placeholder,
+                position: opts.position,
+                placement: opts.placement,
+                conversational: opts.conversational,
+                maxTurns: opts.maxTurns,
+                persistConversation: opts.persistConversation,
+                feedback: opts.feedback,
+                // Base URL used to turn cited doc paths into links.
+                linkBase: ctx.config.site.url ?? "",
+                turnstileSitekey: opts.turnstileSitekey,
+            };
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAmB,MAAM,aAAa,CAAC;AAE5D,6EAA6E;AAC7E,oEAAoE;AACpE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAChE,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;AACpD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;AACvD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;AACjE,4EAA4E;AAC5E,uEAAuE;AACvE,2DAA2D;AAC3D,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC;AAI/E,MAAM,CAAC,OAAO,UAAU,GAAG,CAAC,KAAkB;IAC5C,MAAM,IAAI,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAEjC,OAAO;QACL,IAAI,EAAE,qBAAqB;QAE3B,aAAa;YACX,OAAO,CAAC,WAAW,CAAC,CAAC;QACvB,CAAC;QAED,MAAM;YACJ,OAAO,CAAC,WAAW,CAAC,CAAC;QACvB,CAAC;QAED,iBAAiB;YACf,uEAAuE;YACvE,wEAAwE;YACxE,uEAAuE;YACvE,IAAI,IAAI,CAAC,SAAS,KAAK,UAAU;gBAAE,OAAO,EAAE,CAAC;YAC7C,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;QAC1C,CAAC;QAED,kBAAkB,CAAC,GAAG;YACpB,sCAAsC;YACtC,oDAAoD;YACpD,OAAO;gBACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;gBAC7C,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,oDAAoD;gBACpD,QAAQ,EAAG,GAAG,CAAC,MAAM,CAAC,IAAyB,CAAC,GAAG,IAAI,EAAE;gBACzD,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;aACxC,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/md.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Minimal, dependency-free, XSS-safe Markdown → HTML renderer for LLM answers.
+ *
+ * Safety model: the entire source is HTML-escaped FIRST, so any markup in the
+ * answer becomes inert text; only the tags this renderer emits are real. Link
+ * targets are restricted to http(s)/relative/anchor (no javascript: etc.).
+ *
+ * Scope: headings, bold, italic, inline code, fenced code, ordered/unordered
+ * lists, links, paragraphs — enough for documentation answers. Unsupported
+ * constructs degrade to readable text.
+ */
+export declare function escapeHtml(s: string): string;
+export declare function renderMarkdown(src: string): string;
+//# sourceMappingURL=md.d.ts.map

package/dist/md.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"md.d.ts","sourceRoot":"","sources":["../src/md.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAM5C;AAmBD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAuClD"}

package/dist/md.js

@@ -0,0 +1,115 @@
+/**
+ * Minimal, dependency-free, XSS-safe Markdown → HTML renderer for LLM answers.
+ *
+ * Safety model: the entire source is HTML-escaped FIRST, so any markup in the
+ * answer becomes inert text; only the tags this renderer emits are real. Link
+ * targets are restricted to http(s)/relative/anchor (no javascript: etc.).
+ *
+ * Scope: headings, bold, italic, inline code, fenced code, ordered/unordered
+ * lists, links, paragraphs — enough for documentation answers. Unsupported
+ * constructs degrade to readable text.
+ */
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function isSafeUrl(u) {
+    // u is already HTML-escaped. Allow absolute http(s), root/relative, anchors.
+    return /^(https?:\/\/|\/|#|\.\/|[A-Za-z0-9._~-]+\/)/.test(u) && !/^\s*javascript:/i.test(u);
+}
+// Inline formatting on already-escaped text.
+function inline(text) {
+    let t = text.replace(/`([^`]+)`/g, (_m, c) => `<code>${c}</code>`);
+    t = t.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (_m, label, url) => isSafeUrl(url) ? `<a href="${url}">${label}</a>` : label);
+    t = t.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    t = t.replace(/(^|[^*])\*([^*\n]+)\*/g, "$1<em>$2</em>");
+    t = t.replace(/(^|[^_])_([^_\n]+)_/g, "$1<em>$2</em>");
+    return t;
+}
+export function renderMarkdown(src) {
+    const lines = escapeHtml(src).split(/\r?\n/);
+    let html = "";
+    let ul = false;
+    let ol = false;
+    const closeLists = () => {
+        if (ul) {
+            html += "</ul>";
+            ul = false;
+        }
+        if (ol) {
+            html += "</ol>";
+            ol = false;
+        }
+    };
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (/^\s*```/.test(line)) {
+            closeLists();
+            i++;
+            let code = "";
+            while (i < lines.length && !/^\s*```/.test(lines[i])) {
+                code += lines[i] + "\n";
+                i++;
+            }
+            i++; // closing fence
+            html += `<pre><code>${code}</code></pre>`;
+            continue;
+        }
+        const h = line.match(/^(#{1,6})\s+(.*)$/);
+        if (h) {
+            closeLists();
+            const lvl = h[1].length;
+            html += `<h${lvl}>${inline(h[2])}</h${lvl}>`;
+            i++;
+            continue;
+        }
+        const uli = line.match(/^\s*[-*+]\s+(.*)$/);
+        if (uli) {
+            if (ol) {
+                html += "</ol>";
+                ol = false;
+            }
+            if (!ul) {
+                html += "<ul>";
+                ul = true;
+            }
+            html += `<li>${inline(uli[1])}</li>`;
+            i++;
+            continue;
+        }
+        const oli = line.match(/^\s*\d+\.\s+(.*)$/);
+        if (oli) {
+            if (ul) {
+                html += "</ul>";
+                ul = false;
+            }
+            if (!ol) {
+                html += "<ol>";
+                ol = true;
+            }
+            html += `<li>${inline(oli[1])}</li>`;
+            i++;
+            continue;
+        }
+        if (line.trim() === "") {
+            closeLists();
+            i++;
+            continue;
+        }
+        closeLists();
+        let para = line;
+        i++;
+        while (i < lines.length && lines[i].trim() !== "" && !/^(\s*```|#{1,6}\s|\s*[-*+]\s|\s*\d+\.\s)/.test(lines[i])) {
+            para += " " + lines[i];
+            i++;
+        }
+        html += `<p>${inline(para)}</p>`;
+    }
+    closeLists();
+    return html;
+}
+//# sourceMappingURL=md.js.map

package/dist/md.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"md.js","sourceRoot":"","sources":["../src/md.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Wire protocol shared between the client widget and the dogsbay-ask proxy.
+ * Kept dependency-free and DOM-free so it is unit-testable in Node.
+ */
+import type { AskMode } from "./schema.js";
+export interface AskRequest {
+    site: string;
+    query: string;
+    mode: AskMode;
+}
+export interface ChatMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export interface ChatRequest {
+    site: string;
+    mode: "chat";
+    messages: ChatMessage[];
+}
+/** Build the JSON body the proxy expects. Trims the query. */
+export declare function buildAskRequest(site: string, query: string, mode: AskMode): AskRequest;
+/**
+ * Whether a failed request should be retried once after obtaining a Turnstile
+ * token. The proxy 403s when a Turnstile secret is configured but no valid
+ * token arrived — which happens if the widget submits before the bot token has
+ * resolved (the docked panel lazy-loads Turnstile on focus). Retry only that
+ * case: a 403 while Turnstile is enabled on this site.
+ */
+export declare function shouldRetryTurnstile(status: number, turnstileEnabled: boolean): boolean;
+/** Build the JSON body for a multi-turn chat request. */
+export declare function buildChatRequest(site: string, messages: ChatMessage[]): ChatRequest;
+export interface FeedbackRequest {
+    type: "feedback";
+    askId: string;
+    rating: 1 | -1;
+}
+/**
+ * Build the JSON body for a thumbs up/down vote on a prior answer. `askId` is
+ * the `X-Ask-Id` the proxy stamped on that answer; `rating` is +1 (helpful) or
+ * -1 (not helpful). The proxy records it only when analytics is configured.
+ */
+export declare function buildFeedbackRequest(askId: string, rating: 1 | -1): FeedbackRequest;
+/**
+ * Trim conversation history to the last `maxTurns` messages, never leading with
+ * an `assistant` turn — the proxy prepends the `system` message, so the first
+ * sent message must be a `user`. Returns a new array.
+ */
+export declare function trimHistory(messages: ChatMessage[], maxTurns: number): ChatMessage[];
+/**
+ * Tolerant extraction of human-readable text from a streamed proxy chunk.
+ *
+ * The proxy passes AI Search's streamed answer straight through. Depending on
+ * the instance/model that arrives either as raw text or as SSE `data:` frames.
+ * This strips common SSE framing and ignores the `[DONE]` sentinel so the
+ * widget can append whatever is left. Returns "" for control-only lines.
+ *
+ * NOTE: citation/structured-answer rendering is finalized against a live
+ * instance — see README "Streaming format".
+ */
+export declare function extractText(chunk: string): string;
+export interface Source {
+    key: string;
+    label: string;
+    href: string | null;
+}
+/**
+ * Map an AI Search item key (a "__"-encoded doc path) back to a doc link.
+ * Non-lossy keys reverse to `<linkBase>/<path>`; lossy (hash-suffixed) keys
+ * can't be reconstructed, so they get a readable label with no href.
+ */
+export declare function sourceLink(key: string, linkBase: string): Source;
+/** Find the AI Search `event: chunks` frame in a raw stream and map it to deduped sources. */
+export declare function parseSources(rawStream: string, linkBase: string): Source[];
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,UAAU,CAEtF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,GAAG,OAAO,CAEvF;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,WAAW,CAEnF;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,eAAe,CAEnF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAMpF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA8BjD;AAED,MAAM,WAAW,MAAM;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAUD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUhE;AAED,8FAA8F;AAC9F,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAsB1E"}

package/dist/protocol.js

@@ -0,0 +1,136 @@
+/** Build the JSON body the proxy expects. Trims the query. */
+export function buildAskRequest(site, query, mode) {
+    return { site, query: query.trim(), mode };
+}
+/**
+ * Whether a failed request should be retried once after obtaining a Turnstile
+ * token. The proxy 403s when a Turnstile secret is configured but no valid
+ * token arrived — which happens if the widget submits before the bot token has
+ * resolved (the docked panel lazy-loads Turnstile on focus). Retry only that
+ * case: a 403 while Turnstile is enabled on this site.
+ */
+export function shouldRetryTurnstile(status, turnstileEnabled) {
+    return status === 403 && turnstileEnabled;
+}
+/** Build the JSON body for a multi-turn chat request. */
+export function buildChatRequest(site, messages) {
+    return { site, mode: "chat", messages };
+}
+/**
+ * Build the JSON body for a thumbs up/down vote on a prior answer. `askId` is
+ * the `X-Ask-Id` the proxy stamped on that answer; `rating` is +1 (helpful) or
+ * -1 (not helpful). The proxy records it only when analytics is configured.
+ */
+export function buildFeedbackRequest(askId, rating) {
+    return { type: "feedback", askId, rating };
+}
+/**
+ * Trim conversation history to the last `maxTurns` messages, never leading with
+ * an `assistant` turn — the proxy prepends the `system` message, so the first
+ * sent message must be a `user`. Returns a new array.
+ */
+export function trimHistory(messages, maxTurns) {
+    let trimmed = messages.slice(-Math.max(1, maxTurns));
+    while (trimmed.length > 0 && trimmed[0].role === "assistant") {
+        trimmed = trimmed.slice(1);
+    }
+    return trimmed;
+}
+/**
+ * Tolerant extraction of human-readable text from a streamed proxy chunk.
+ *
+ * The proxy passes AI Search's streamed answer straight through. Depending on
+ * the instance/model that arrives either as raw text or as SSE `data:` frames.
+ * This strips common SSE framing and ignores the `[DONE]` sentinel so the
+ * widget can append whatever is left. Returns "" for control-only lines.
+ *
+ * NOTE: citation/structured-answer rendering is finalized against a live
+ * instance — see README "Streaming format".
+ */
+export function extractText(chunk) {
+    return chunk
+        .split(/\r?\n/)
+        .map((line) => {
+        const trimmed = line.trimStart();
+        if (trimmed === "")
+            return "";
+        // Drop SSE control framing (event:/id:/retry:/comment) — only `data:`
+        // lines carry content. A `data: [...]` chunks array parses to an array
+        // with no token field and is harmlessly skipped below.
+        if (/^(event|id|retry):/.test(trimmed) || trimmed.startsWith(":"))
+            return "";
+        if (!trimmed.startsWith("data:"))
+            return line;
+        const payload = trimmed.slice("data:".length).trim();
+        if (payload === "" || payload === "[DONE]")
+            return "";
+        // Try to pull a token out of a JSON event; else emit raw payload.
+        // Handles OpenAI-compatible chat-completions chunks
+        // ({choices:[{delta:{content}}]}) plus a few simpler shapes.
+        try {
+            const obj = JSON.parse(payload);
+            const token = obj.choices?.[0]?.delta?.content ??
+                obj.choices?.[0]?.message?.content ??
+                obj.response ??
+                obj.text ??
+                obj.delta;
+            return typeof token === "string" ? token : "";
+        }
+        catch {
+            return payload;
+        }
+    })
+        .join("");
+}
+// Ingest-script lossy shortener produces `<head>__<leaf>__<8hex>.md` for paths
+// too long to fit the filename limit — those can't be reversed to a real URL.
+const LOSSY = /__[0-9a-f]{8}\.md$/;
+function humanize(seg) {
+    return seg.replace(/[-_]+/g, " ").trim();
+}
+/**
+ * Map an AI Search item key (a "__"-encoded doc path) back to a doc link.
+ * Non-lossy keys reverse to `<linkBase>/<path>`; lossy (hash-suffixed) keys
+ * can't be reconstructed, so they get a readable label with no href.
+ */
+export function sourceLink(key, linkBase) {
+    const base = (linkBase || "").replace(/\/+$/, "");
+    if (LOSSY.test(key)) {
+        const parts = key.replace(/\.md$/, "").split("__");
+        const leaf = parts.length >= 2 ? parts[parts.length - 2] : parts[0];
+        return { key, label: humanize(leaf), href: null };
+    }
+    const path = key.replace(/\.md$/, "").split("__").join("/");
+    const leaf = path.split("/").pop() || path;
+    return { key, label: humanize(leaf), href: base ? `${base}/${path}` : `/${path}` };
+}
+/** Find the AI Search `event: chunks` frame in a raw stream and map it to deduped sources. */
+export function parseSources(rawStream, linkBase) {
+    for (const raw of rawStream.split(/\r?\n/)) {
+        const line = raw.trimStart();
+        if (!line.startsWith("data:"))
+            continue;
+        const payload = line.slice("data:".length).trim();
+        if (!payload.startsWith("["))
+            continue;
+        try {
+            const arr = JSON.parse(payload);
+            const seen = new Set();
+            const out = [];
+            for (const c of arr) {
+                const key = typeof c.item === "string" ? c.item : c.item?.key;
+                if (!key || seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push(sourceLink(key, linkBase));
+            }
+            if (out.length)
+                return out;
+        }
+        catch {
+            // not the chunks frame; keep scanning
+        }
+    }
+    return [];
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Options schema for `@dogsbay/plugin-ask`.
+ *
+ * Hand-rolled validation (no Zod dep), matching the convention in
+ * `@dogsbay/plugin-image-zoom`. `parseOptions` returns a fully-resolved
+ * options object with every field set to either the user value or the
+ * documented default. `endpoint` and `site` are REQUIRED — the widget is
+ * useless without a backend to call and a site id to route by.
+ */
+export type AskMode = "answer" | "search";
+export type AskPosition = "bottom-right" | "bottom-left";
+/**
+ * Where the widget renders.
+ * - `auto` (default) — dock as a panel in the docs right rail when one exists
+ *   (Dogsbay's `DocsLayout` `right-rail` slot), else fall back to a floating
+ *   button + dialog.
+ * - `rail` — always contribute the docked rail panel (no desktop floating button).
+ * - `floating` — the floating button + modal only; never use the rail.
+ */
+export type AskPlacement = "auto" | "rail" | "floating";
+export interface AskOptions {
+    /**
+     * URL of the dogsbay-ask proxy (the shared Worker). Required.
+     * Example: "https://dogsbay-ask.<subdomain>.workers.dev".
+     */
+    endpoint?: string;
+    /**
+     * Site id sent to the proxy to select the AI Search instance. Required.
+     * This is the site's GitHub Pages subfolder / Dogsbay base path, e.g.
+     * "openshift-docs-dogsbay". Must match a key in the proxy's SITES map.
+     */
+    site?: string;
+    /** Retrieval mode: "answer" (RAG answer, default) or "search" (chunks). */
+    mode?: AskMode;
+    /**
+     * Multi-turn conversation: keep prior turns on screen and send them as
+     * context so follow-ups are understood. Default `true`. Set `false` for the
+     * single-shot behaviour (one question → one answer, no history).
+     */
+    conversational?: boolean;
+    /**
+     * Max prior messages sent as context when `conversational` (bounds prompt
+     * size / cost / latency). Positive integer; default `8`.
+     */
+    maxTurns?: number;
+    /**
+     * Persist the conversation in `sessionStorage` (tab-scoped, cleared when the
+     * tab closes) so it survives a page refresh and same-window navigation (e.g.
+     * clicking a source link). Default `true`. Readers can still opt out via the
+     * widget's "Remember conversation" toggle. Set `false` to disable persistence
+     * site-wide. Only applies in `conversational` answer mode.
+     */
+    persistConversation?: boolean;
+    /**
+     * Show a 👍/👎 helpfulness control under each answer. The vote is sent to the
+     * proxy referencing the answer's id; the proxy stores it only if analytics is
+     * configured (otherwise it is a no-op). Default `true`. Set `false` to hide.
+     */
+    feedback?: boolean;
+    /** Floating button label. Default "Ask AI". */
+    buttonLabel?: string;
+    /** Modal heading. Default "Ask the docs". */
+    title?: string;
+    /** Input placeholder. Default "Ask a question…". */
+    placeholder?: string;
+    /** Corner the floating button sits in. Default "bottom-right". */
+    position?: AskPosition;
+    /**
+     * Where the widget renders: docked rail panel, floating modal, or `auto`.
+     * Default "auto". See {@link AskPlacement}.
+     */
+    placement?: AskPlacement;
+    /**
+     * Cloudflare Turnstile sitekey. If set, the widget obtains a Turnstile
+     * token and sends it with each request; the proxy verifies it. Omit to
+     * disable the bot check.
+     */
+    turnstileSitekey?: string;
+}
+export interface ResolvedAskOptions {
+    endpoint: string;
+    site: string;
+    mode: AskMode;
+    buttonLabel: string;
+    title: string;
+    placeholder: string;
+    position: AskPosition;
+    placement: AskPlacement;
+    conversational: boolean;
+    maxTurns: number;
+    persistConversation: boolean;
+    feedback: boolean;
+    turnstileSitekey: string;
+}
+/**
+ * Validate + resolve user options. Throws structured errors naming the
+ * offending field so users see a clear message rather than a stack trace.
+ */
+export declare function parseOptions(input: unknown): ResolvedAskOptions;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC1C,MAAM,MAAM,WAAW,GAAG,cAAc,GAAG,aAAa,CAAC;AACzD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,YAAY,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,WAAW,CAAC;IACtB,SAAS,EAAE,YAAY,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAkBD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CA+D/D"}

package/dist/schema.js

@@ -0,0 +1,113 @@
+/**
+ * Options schema for `@dogsbay/plugin-ask`.
+ *
+ * Hand-rolled validation (no Zod dep), matching the convention in
+ * `@dogsbay/plugin-image-zoom`. `parseOptions` returns a fully-resolved
+ * options object with every field set to either the user value or the
+ * documented default. `endpoint` and `site` are REQUIRED — the widget is
+ * useless without a backend to call and a site id to route by.
+ */
+const DEFAULTS = {
+    mode: "answer",
+    buttonLabel: "Ask AI",
+    title: "Ask the docs",
+    placeholder: "Ask a question…",
+    position: "bottom-right",
+    placement: "auto",
+    conversational: true,
+    maxTurns: 8,
+    persistConversation: true,
+    feedback: true,
+    turnstileSitekey: "",
+};
+const PKG = "@dogsbay/plugin-ask";
+/**
+ * Validate + resolve user options. Throws structured errors naming the
+ * offending field so users see a clear message rather than a stack trace.
+ */
+export function parseOptions(input) {
+    if (input === undefined || input === null || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error(`${PKG}: options are required and must be an object with at least { endpoint, site }, got ${describe(input)}.`);
+    }
+    const opts = input;
+    const endpoint = requireUrl(opts.endpoint, "endpoint");
+    const site = requireNonEmptyString(opts.site, "site");
+    const out = { ...DEFAULTS, endpoint, site };
+    if (opts.mode !== undefined) {
+        if (opts.mode !== "answer" && opts.mode !== "search") {
+            throw new Error(`${PKG}: options.mode must be "answer" or "search".`);
+        }
+        out.mode = opts.mode;
+    }
+    if (opts.buttonLabel !== undefined)
+        out.buttonLabel = requireNonEmptyString(opts.buttonLabel, "buttonLabel");
+    if (opts.title !== undefined)
+        out.title = requireNonEmptyString(opts.title, "title");
+    if (opts.placeholder !== undefined)
+        out.placeholder = requireNonEmptyString(opts.placeholder, "placeholder");
+    if (opts.position !== undefined) {
+        if (opts.position !== "bottom-right" && opts.position !== "bottom-left") {
+            throw new Error(`${PKG}: options.position must be "bottom-right" or "bottom-left".`);
+        }
+        out.position = opts.position;
+    }
+    if (opts.placement !== undefined) {
+        if (opts.placement !== "auto" && opts.placement !== "rail" && opts.placement !== "floating") {
+            throw new Error(`${PKG}: options.placement must be "auto", "rail", or "floating".`);
+        }
+        out.placement = opts.placement;
+    }
+    if (opts.conversational !== undefined) {
+        if (typeof opts.conversational !== "boolean") {
+            throw new Error(`${PKG}: options.conversational must be a boolean.`);
+        }
+        out.conversational = opts.conversational;
+    }
+    if (opts.maxTurns !== undefined) {
+        if (typeof opts.maxTurns !== "number" || !Number.isInteger(opts.maxTurns) || opts.maxTurns < 1) {
+            throw new Error(`${PKG}: options.maxTurns must be a positive integer.`);
+        }
+        out.maxTurns = opts.maxTurns;
+    }
+    if (opts.persistConversation !== undefined) {
+        if (typeof opts.persistConversation !== "boolean") {
+            throw new Error(`${PKG}: options.persistConversation must be a boolean.`);
+        }
+        out.persistConversation = opts.persistConversation;
+    }
+    if (opts.feedback !== undefined) {
+        if (typeof opts.feedback !== "boolean") {
+            throw new Error(`${PKG}: options.feedback must be a boolean.`);
+        }
+        out.feedback = opts.feedback;
+    }
+    if (opts.turnstileSitekey !== undefined) {
+        out.turnstileSitekey = requireNonEmptyString(opts.turnstileSitekey, "turnstileSitekey");
+    }
+    return out;
+}
+function requireNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${PKG}: options.${field} must be a non-empty string.`);
+    }
+    return value;
+}
+function requireUrl(value, field) {
+    const s = requireNonEmptyString(value, field);
+    try {
+        // eslint-disable-next-line no-new
+        new URL(s);
+    }
+    catch {
+        throw new Error(`${PKG}: options.${field} must be a valid absolute URL, got "${s}".`);
+    }
+    return s;
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+//# sourceMappingURL=schema.js.map