vuepress-plugin-ai-chatbot 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Asyntai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# vuepress-plugin-ai-chatbot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add the [Asyntai](https://asyntai.com) AI chat assistant to your VuePress site.
+It answers visitor questions from your own documentation, in more than 80
+languages.
+
+## Install
+
+```bash
+npm install -D vuepress-plugin-ai-chatbot
+```
+
+Then add the plugin in `.vuepress/config.js` (or `config.ts`):
+
+```js
+import { defineUserConfig } from 'vuepress';
+import { aiChatbotPlugin } from 'vuepress-plugin-ai-chatbot';
+
+export default defineUserConfig({
+  plugins: [
+    aiChatbotPlugin({ widgetId: 'asyntai_1a2b3c4d5e6f' }),
+  ],
+});
+```
+
+Build the site. The chat bubble is on every page.
+
+## Where the widget ID comes from
+
+Open the Install page in your [Asyntai dashboard](https://asyntai.com/dashboard).
+The widget ID is the value of `data-asyntai-id` in the snippet shown there. It
+starts with `asyntai_`.
+
+Creating an account is free, and the Free plan is enough to try the widget.
+
+## Options
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `widgetId` | string | required | Your Asyntai widget ID |
+| `enableInDevelopment` | boolean | `true` | Set to `false` to keep the widget off the site during `vuepress dev` |
+| `scriptUrl` | string | the Asyntai CDN | Advanced. Load the widget from another URL |
+
+A missing or malformed `widgetId` stops the build with a message that says how
+to fix it.
+
+## What the plugin does
+
+- It adds the Asyntai loader to the head of every page.
+- The loader waits for the page's `load` event, so your own content always
+  renders first.
+- It works with the default theme and with any other theme, and the chat stays
+  open while the visitor moves between pages.
+- If your `head` config already has an Asyntai snippet, the plugin adds no
+  second one.
+
+## Answering from your content
+
+Asyntai reads your published pages. Add your site URL in the dashboard, and the
+assistant answers from the same pages the widget sits on. You can also add extra
+documents and question and answer pairs.
+
+## VuePress versions
+
+VuePress 2. Both `vuepress build` and `vuepress dev` put the widget on every
+page.
+
+## TypeScript
+
+Types ship with the package.
+
+## Removing it
+
+Delete the `aiChatbotPlugin` line from the config and build again. The widget is
+gone.
+
+## Support
+
+Email [hello@asyntai.com](mailto:hello@asyntai.com), or read the
+[VuePress guide](https://asyntai.com/documentation/integrations/vuepress/).
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "vuepress-plugin-ai-chatbot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Add the Asyntai AI chat assistant to your VuePress site. It answers visitor questions from your own docs, in 80+ languages.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "vuepress",
+    "vuepress-plugin",
+    "vuepress2",
+    "chatbot",
+    "ai",
+    "chat",
+    "live-chat",
+    "support",
+    "documentation",
+    "asyntai"
+  ],
+  "homepage": "https://asyntai.com/documentation/integrations/vuepress/",
+  "bugs": {
+    "url": "https://github.com/asyntai/vuepress-plugin-ai-chatbot/issues",
+    "email": "hello@asyntai.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyntai/vuepress-plugin-ai-chatbot.git"
+  },
+  "author": "Asyntai <hello@asyntai.com> (https://asyntai.com)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.19"
+  },
+  "scripts": {
+    "test": "node tests/test_plugin.js"
+  },
+  "peerDependencies": {
+    "vuepress": "^2.0.0-rc.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from 'vuepress/core';
+
+export interface AiChatbotPluginOptions {
+  /** Your Asyntai widget ID, for example `asyntai_1a2b3c4d5e6f`. Required. */
+  widgetId: string;
+  /** Set to false to keep the widget off the site during `vuepress dev`. */
+  enableInDevelopment?: boolean;
+  /** Advanced. Load the widget script from another URL. */
+  scriptUrl?: string;
+}
+
+export declare const aiChatbotPlugin: (options: AiChatbotPluginOptions) => Plugin;
+export default aiChatbotPlugin;

package/src/index.js

@@ -0,0 +1,27 @@
+/**
+ * Asyntai AI chatbot for VuePress 2.
+ *
+ * Adds the Asyntai chat widget to every page of the site. VuePress owns the
+ * HTML of each page, so the plugin adds the ordinary embed loader to the site
+ * head and changes nothing else about the site.
+ */
+
+import { NAME, addToHead, validateOptions } from './loader.js';
+
+export const aiChatbotPlugin = (options) => {
+  const settings = validateOptions(options);
+
+  return {
+    name: NAME,
+
+    onInitialized(app) {
+      if (app.env.isDev && !settings.enableInDevelopment) {
+        return;
+      }
+      app.siteData.head = app.siteData.head || [];
+      addToHead(app.siteData.head, settings);
+    },
+  };
+};
+
+export default aiChatbotPlugin;

package/src/loader.js

@@ -0,0 +1,104 @@
+/**
+ * Option handling and the embed snippet for vuepress-plugin-ai-chatbot.
+ *
+ * This file has no dependencies, so the tests run it on its own, without a
+ * VuePress install.
+ */
+
+export const DEFAULT_SCRIPT_URL = 'https://widget.asyntai.com/static/js/chat-widget.js';
+export const NAME = 'vuepress-plugin-ai-chatbot';
+
+const WIDGET_ID_PATTERN = /^asyntai_[A-Za-z0-9]+$/;
+
+/**
+ * VuePress calls the plugin before it builds anything, so a wrong option stops
+ * the build with a clear message instead of producing a site with no chat on it.
+ */
+export function validateOptions(options) {
+  const opts = options || {};
+  const widgetId = typeof opts.widgetId === 'string' ? opts.widgetId.trim() : '';
+
+  if (!widgetId) {
+    throw new Error(
+      NAME +
+        ': "widgetId" is required. Copy it from the Install page of your ' +
+        'Asyntai dashboard, for example asyntai_1a2b3c4d5e6f.',
+    );
+  }
+  if (!WIDGET_ID_PATTERN.test(widgetId)) {
+    throw new Error(
+      NAME +
+        ': "' +
+        widgetId +
+        '" does not look like a widget ID. It starts with asyntai_, for ' +
+        'example asyntai_1a2b3c4d5e6f.',
+    );
+  }
+
+  const scriptUrl =
+    typeof opts.scriptUrl === 'string' && opts.scriptUrl.trim()
+      ? opts.scriptUrl.trim()
+      : DEFAULT_SCRIPT_URL;
+
+  return {
+    widgetId,
+    scriptUrl,
+    // Set to false to keep the widget off the site during `vuepress dev`.
+    enableInDevelopment: opts.enableInDevelopment !== false,
+  };
+}
+
+/** JSON.stringify, safe inside an HTML <script> element. */
+function jsString(value) {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+/**
+ * The loader waits for the page's load event before it fetches the widget.
+ * An ordinary `<script async src>` holds the load event open until its own
+ * fetch finishes, so an unreachable server would delay the host page. This
+ * pattern cannot.
+ */
+export function buildLoader(widgetId, scriptUrl) {
+  return (
+    '(function(){var l=function(){' +
+    'if(document.querySelector("script[data-asyntai-id]"))return;' +
+    'var s=document.createElement("script");' +
+    's.src=' +
+    jsString(scriptUrl) +
+    ';s.async=true;' +
+    's.setAttribute("data-asyntai-id",' +
+    jsString(widgetId) +
+    ');' +
+    'document.head.appendChild(s)};' +
+    'if(document.readyState==="complete"){l()}' +
+    'else{window.addEventListener("load",l)}})();'
+  );
+}
+
+/** The VuePress head entry: [tag, attributes, inner code]. */
+export function buildHeadTag(settings) {
+  return [
+    'script',
+    { 'data-asyntai-loader': true },
+    buildLoader(settings.widgetId, settings.scriptUrl),
+  ];
+}
+
+/** True for a head entry this plugin (or a hand-made snippet) already added. */
+export function isAsyntaiTag(entry) {
+  if (!Array.isArray(entry) || entry[0] !== 'script') {
+    return false;
+  }
+  const attrs = entry[1] || {};
+  return 'data-asyntai-loader' in attrs || 'data-asyntai-id' in attrs;
+}
+
+/** Adds the loader to the site head once. Returns true when it added it. */
+export function addToHead(head, settings) {
+  if (head.some(isAsyntaiTag)) {
+    return false;
+  }
+  head.push(buildHeadTag(settings));
+  return true;
+}