@deskcrew/sveltekit 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,57 @@
+# @deskcrew/sveltekit
+
+Add the [DeskCrew](https://deskcrew.io) support widget to a SvelteKit app: live chat, AI answers grounded in your knowledge base, and a help center. One server hook, and every page (server-rendered or prerendered) carries the widget, isolated in a Shadow DOM.
+
+## Install
+
+```
+npm install @deskcrew/sveltekit
+```
+
+In `src/hooks.server.js` (or `.ts`):
+
+```js
+import { deskcrewHandle } from '@deskcrew/sveltekit'
+
+export const handle = deskcrewHandle({ widgetKey: 'pub_your_widget_key', board: 'your-board' })
+```
+
+Already have a `handle`? Compose them:
+
+```js
+import { sequence } from '@sveltejs/kit/hooks'
+import { deskcrewHandle } from '@deskcrew/sveltekit'
+
+export const handle = sequence(myHandle, deskcrewHandle({ widgetKey: 'pub_your_widget_key' }))
+```
+
+Prefer a static tag? Paste the output of `buildTag(options).tag` into `src/app.html` before `</body>`; the hook does the same thing at request time.
+
+Get the key from the Install page of your DeskCrew dashboard.
+
+## What you get
+
+- **AI answers grounded in your own help articles.** The assistant only answers from the knowledge base you publish, so it cannot invent product facts.
+- **A human approves before anything sends.** Every AI draft waits in an approval queue. Nothing reaches a customer unreviewed.
+- **Every conversation becomes a ticket.** Widget chats, emails and board posts land in one dashboard with full history.
+- **Visitors who leave still get answered.** Leave an email address and the reply arrives by email.
+
+## Options
+
+| Option      | Required | Notes                                                                                |
+| ----------- | -------- | ------------------------------------------------------------------------------------ |
+| `widgetKey` | yes      | Your public widget key, `pub_...`, from the Install page of your DeskCrew dashboard. |
+| `board`     | no       | Your board slug (lowercase letters, numbers, dashes). Enables the feedback link.     |
+| `color`     | no       | Accent colour as a 6-digit hex value, e.g. `#4f46e5`.                                |
+| `position`  | no       | `right` (default) or `left`.                                                         |
+| `greeting`  | no       | First line the launcher shows.                                                       |
+
+Invalid optional values are dropped with a console warning; a missing or malformed key means the widget is not added at all, so a bad config can never put arbitrary markup on your page.
+
+## Privacy
+
+The only thing this package adds to your site is one `<script>` tag that loads `https://deskcrew.io/desk.js` with your public key. The widget runs inside a Shadow DOM and does not touch your styles. Terms: https://deskcrew.io/terms. Privacy: https://deskcrew.io/privacy.
+
+## License
+
+MIT

package/build-tag.js

@@ -0,0 +1,143 @@
+// Framework-agnostic core for the DeskCrew widget packages.
+//
+// Everything here is a pure function of its options: no Astro imports, no I/O,
+// so it can be unit-tested on its own (see test/build-tag.mjs).
+
+/** The canonical DeskCrew widget bundle. desk.js derives its API origin from this src. */
+export 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[] }}
+ */
+export 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 for the widget (handy for
+ * debugging or manual placement), or `null` when options are invalid.
+ *
+ * @param {Record<string, unknown> | undefined | null} options
+ * @returns {{ tag: string | null, warnings: string[] }}
+ */
+export 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 }
+}
+
+/**
+ * Escape a string for safe embedding as a JS literal inside an inline <script>.
+ * `<`, `>` and `&` are escaped so a value can never close the inline script tag.
+ * @param {unknown} value
+ */
+function jsLiteral(value) {
+  return JSON.stringify(String(value))
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+}
+
+/**
+ * Astro's `injectScript('head-inline', ...)` takes JS, not a raw external tag,
+ * so we emit a tiny bootstrap that creates the widget <script> element and
+ * appends it. Returns `{ code: null }` when options are invalid.
+ *
+ * @param {Record<string, unknown> | undefined | null} options
+ * @returns {{ code: string | null, warnings: string[] }}
+ */
+export function buildBootstrap(options) {
+  const { attrs, warnings } = buildAttrs(options)
+  if (!attrs) return { code: null, warnings }
+
+  const dataLines = attrs
+    .filter(([name]) => name !== 'src')
+    .map(([name, value]) => `  s.setAttribute(${jsLiteral(name)}, ${jsLiteral(value)});`)
+    .join('\n')
+
+  const guard = `script[src=${JSON.stringify(WIDGET_SRC)}]`
+  const code =
+    '(function () {\n' +
+    `  if (document.querySelector(${jsLiteral(guard)})) return;\n` +
+    '  var s = document.createElement("script");\n' +
+    `  s.src = ${jsLiteral(WIDGET_SRC)};\n` +
+    '  s.defer = true;\n' +
+    (dataLines ? dataLines + '\n' : '') +
+    '  document.head.appendChild(s);\n' +
+    '})();'
+
+  return { code, warnings }
+}

package/index.d.ts

@@ -0,0 +1,19 @@
+export interface DeskcrewOptions {
+  /** 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 (defaults to the widget's own default). */
+  position?: 'left' | 'right'
+  /** Greeting shown on the launcher. Optional. */
+  greeting?: string
+}
+
+import type { Handle } from '@sveltejs/kit'
+
+/** A `handle` hook for src/hooks.server.js that injects the widget on every HTML page. */
+export function deskcrewHandle(options: DeskcrewOptions): Handle
+export default deskcrewHandle
+export function buildTag(options: DeskcrewOptions): { tag: string | null; warnings: string[] }

package/index.js

@@ -0,0 +1,31 @@
+import { buildTag } from './build-tag.js'
+
+/**
+ * A SvelteKit `handle` hook that injects the DeskCrew widget <script> before
+ * </body> on every HTML page, server-rendered or prerendered.
+ *
+ *   // src/hooks.server.js
+ *   import { deskcrewHandle } from '@deskcrew/sveltekit'
+ *   export const handle = deskcrewHandle({ widgetKey: 'pub_...' })
+ *
+ * Compose with your own hooks through `sequence` from '@sveltejs/kit/hooks'.
+ *
+ * @param {import('./index.js').DeskcrewOptions} options
+ */
+export function deskcrewHandle(options) {
+  const { tag, warnings } = buildTag(options)
+  for (const message of warnings) console.warn(message)
+  return async ({ event, resolve }) => {
+    if (!tag) return resolve(event)
+    return resolve(event, {
+      transformPageChunk: ({ html, done }) => {
+        if (!done) return html
+        if (html.includes('https://deskcrew.io/desk.js')) return html
+        return html.replace(/<\/body>/i, `${tag}\n</body>`)
+      },
+    })
+  }
+}
+
+export default deskcrewHandle
+export { buildTag }

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@deskcrew/sveltekit",
+  "version": "1.0.0",
+  "description": "SvelteKit server hook that adds the DeskCrew support widget (live chat, AI answers from your knowledge base, a help center) to every page.",
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "svelte-kit",
+    "hooks",
+    "vite",
+    "support",
+    "helpdesk",
+    "help desk",
+    "customer support",
+    "live chat",
+    "chat widget",
+    "support widget",
+    "ai chat",
+    "ai support",
+    "ticketing",
+    "support tickets",
+    "knowledge base",
+    "deskcrew"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webmilmind1/sveltekit-deskcrew.git"
+  },
+  "homepage": "https://deskcrew.io/integrations/sveltekit",
+  "bugs": {
+    "url": "https://github.com/webmilmind1/sveltekit-deskcrew/issues",
+    "email": "hello@deskcrew.io"
+  },
+  "author": "DeskCrew <hello@deskcrew.io> (https://deskcrew.io)",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./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"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}