@deskcrew/docusaurus-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeskCrew
+
+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

@@ -0,0 +1,65 @@
+# @deskcrew/docusaurus-plugin
+
+Add the [DeskCrew](https://deskcrew.io) support widget — live chat, instant
+answers from your help articles and a help center — to every page of your
+Docusaurus site.
+
+## Install
+
+```bash
+npm install @deskcrew/docusaurus-plugin
+```
+
+## Usage
+
+Add the plugin to your `docusaurus.config.js` and pass your widget key:
+
+```js
+// docusaurus.config.js
+module.exports = {
+  // ...
+  plugins: [
+    [
+      '@deskcrew/docusaurus-plugin',
+      {
+        widgetKey: 'pub_xxxxxxxx', // required — from Dashboard → Install
+        // board: 'your-workspace', // optional
+        // color: '#4f46e5',        // optional accent colour
+        // position: 'right',       // optional: 'left' | 'right'
+        // greeting: 'Hi! How can we help?', // optional
+      },
+    ],
+  ],
+}
+```
+
+Start or build your site and the chat launcher appears on every page.
+
+## Options
+
+| Option      | Type                | Required | Description                                        |
+| ----------- | ------------------- | -------- | -------------------------------------------------- |
+| `widgetKey` | `string`            | yes      | Your public key (`pub_…`).                         |
+| `board`     | `string`            | no       | Board slug (lowercase letters, numbers, dashes).   |
+| `color`     | `string`            | no       | Accent colour as a 6-digit hex value, e.g. `#4f46e5`. |
+| `position`  | `'left' \| 'right'` | no       | Which side the launcher sits on.                   |
+| `greeting`  | `string`            | no       | Greeting shown on the launcher.                    |
+
+If `widgetKey` is missing or malformed the plugin prints a build-time warning
+and adds nothing — your site still builds.
+
+## How it works
+
+The plugin appends a single `<script src="https://deskcrew.io/desk.js">` tag to
+every page via the `injectHtmlTags` lifecycle (`postBodyTags`). `desk.js` reads
+your settings from its `data-*` attributes and derives its API origin from its
+own `src`, so there is nothing else to configure.
+
+## No account yet?
+
+[Create one free](https://deskcrew.io/signup) — no card needed — then copy your
+key from [Dashboard → Install](https://deskcrew.io/dashboard/install).
+
+## License
+
+MIT © DeskCrew · [deskcrew.io](https://deskcrew.io) · hello@deskcrew.io

package/build-tag.js

@@ -0,0 +1,102 @@
+// Framework-agnostic core for the DeskCrew Docusaurus plugin.
+//
+// Everything here is a pure function of its options — no Docusaurus imports, no
+// I/O — so it can be unit-tested on its own (see test/build-tag.cjs).
+
+'use strict'
+
+/** The canonical DeskCrew widget bundle. desk.js derives its API origin from this src. */
+const WIDGET_SRC = 'https://deskcrew.io/desk.js'
+
+// Strict shapes: a value is only ever placed into markup after it matches one of
+// these, so nothing arbitrary can reach the page.
+const KEY_RE = /^pub_[A-Za-z0-9]{8,64}$/
+const BOARD_RE = /^[a-z0-9-]+$/
+const COLOR_RE = /^#[0-9a-fA-F]{6}$/
+const POSITIONS = new Set(['left', 'right'])
+
+/**
+ * Validate options and produce the ordered [name, value] attribute list for the
+ * widget <script>. Returns `{ attrs: null }` (nothing should be injected) when
+ * the widget key is missing or malformed; invalid *optional* values are dropped
+ * with a warning but never block the widget.
+ *
+ * @param {Record<string, unknown> | undefined | null} options
+ * @returns {{ attrs: string[][] | null, warnings: string[] }}
+ */
+function buildAttrs(options) {
+  const warnings = []
+  const opts = options || {}
+
+  const key = typeof opts.widgetKey === 'string' ? opts.widgetKey.trim() : ''
+  if (!key) {
+    warnings.push(
+      '[deskcrew] No widgetKey was provided — the support widget was NOT added. ' +
+        'Copy your pub_ key from https://deskcrew.io/dashboard/install.',
+    )
+    return { attrs: null, warnings }
+  }
+  if (!KEY_RE.test(key)) {
+    warnings.push(
+      `[deskcrew] widgetKey "${key}" is not a valid public key (expected pub_...) — ` +
+        'the support widget was NOT added.',
+    )
+    return { attrs: null, warnings }
+  }
+
+  const attrs = [
+    ['src', WIDGET_SRC],
+    ['data-key', key],
+  ]
+
+  const board = typeof opts.board === 'string' ? opts.board.trim() : ''
+  if (board) {
+    if (BOARD_RE.test(board)) attrs.push(['data-board', board])
+    else warnings.push(`[deskcrew] board "${board}" is not a valid slug (a-z, 0-9, dashes) — ignored.`)
+  }
+
+  const color = typeof opts.color === 'string' ? opts.color.trim() : ''
+  if (color) {
+    if (COLOR_RE.test(color)) attrs.push(['data-color', color])
+    else warnings.push(`[deskcrew] color "${color}" is not a 6-digit hex value like #4f46e5 — ignored.`)
+  }
+
+  const position = typeof opts.position === 'string' ? opts.position.trim() : ''
+  if (position) {
+    if (POSITIONS.has(position)) attrs.push(['data-position', position])
+    else warnings.push(`[deskcrew] position "${position}" must be "left" or "right" — ignored.`)
+  }
+
+  const greeting = typeof opts.greeting === 'string' ? opts.greeting.trim() : ''
+  if (greeting) attrs.push(['data-greeting', greeting])
+
+  return { attrs, warnings }
+}
+
+/**
+ * Escape a value for use inside a double-quoted HTML attribute.
+ * @param {unknown} value
+ */
+function escapeHtmlAttr(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/**
+ * Build the canonical `<script ...>` tag string injected on every page, or
+ * `null` when options are invalid.
+ *
+ * @param {Record<string, unknown> | undefined | null} options
+ * @returns {{ tag: string | null, warnings: string[] }}
+ */
+function buildTag(options) {
+  const { attrs, warnings } = buildAttrs(options)
+  if (!attrs) return { tag: null, warnings }
+  const rendered = attrs.map(([name, value]) => `${name}="${escapeHtmlAttr(value)}"`).join(' ')
+  return { tag: `<script ${rendered} defer></script>`, warnings }
+}
+
+module.exports = { WIDGET_SRC, buildAttrs, buildTag }

package/index.d.ts

@@ -0,0 +1,23 @@
+import type { LoadContext, Plugin } from '@docusaurus/types'
+
+declare function deskcrewPlugin(
+  context: LoadContext,
+  options?: deskcrewPlugin.DeskcrewPluginOptions,
+): Plugin<void>
+
+declare namespace deskcrewPlugin {
+  interface DeskcrewPluginOptions {
+    /** Your DeskCrew public widget key, e.g. "pub_xxxxxxxx". Required. */
+    widgetKey: string
+    /** Board slug (lowercase letters, numbers and dashes). Optional. */
+    board?: string
+    /** Accent colour as a 6-digit hex value, e.g. "#4f46e5". Optional. */
+    color?: string
+    /** Which side the launcher sits on. Optional. */
+    position?: 'left' | 'right'
+    /** Greeting shown on the launcher. Optional. */
+    greeting?: string
+  }
+}
+
+export = deskcrewPlugin

package/index.js

@@ -0,0 +1,27 @@
+'use strict'
+
+const { buildTag } = require('./build-tag.js')
+
+/**
+ * DeskCrew Docusaurus plugin.
+ *
+ * Adds the DeskCrew support widget (live chat, instant answers and a help
+ * centre) to every page. It appends a single `<script src="…/desk.js">` tag via
+ * the `injectHtmlTags` lifecycle (`postBodyTags`); desk.js reads its `data-*`
+ * attributes and derives its API origin from its own src.
+ *
+ * @param {unknown} _context Docusaurus LoadContext (unused).
+ * @param {Record<string, unknown>} [options]
+ * @returns {{ name: string, injectHtmlTags: () => { postBodyTags?: string[] } }}
+ */
+module.exports = function deskcrewPlugin(_context, options) {
+  const { tag, warnings } = buildTag(options || {})
+  for (const message of warnings) console.warn(message)
+
+  return {
+    name: 'docusaurus-plugin-deskcrew',
+    injectHtmlTags() {
+      return tag ? { postBodyTags: [tag] } : {}
+    },
+  }
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@deskcrew/docusaurus-plugin",
+  "version": "1.0.0",
+  "description": "Docusaurus plugin that adds the DeskCrew support widget (live chat, instant answers and a help center) to every page.",
+  "keywords": [
+    "docusaurus",
+    "docusaurus-plugin",
+    "deskcrew",
+    "support",
+    "chat",
+    "widget",
+    "helpdesk",
+    "live-chat"
+  ],
+  "homepage": "https://deskcrew.io",
+  "bugs": {
+    "email": "hello@deskcrew.io"
+  },
+  "author": "DeskCrew <hello@deskcrew.io> (https://deskcrew.io)",
+  "license": "MIT",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "build-tag.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@docusaurus/core": ">=2"
+  },
+  "devDependencies": {
+    "@docusaurus/types": ">=2",
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}