@deskcrew/angular 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,53 @@
+# @deskcrew/angular
+
+Add the [DeskCrew](https://deskcrew.io) support widget to an Angular app: live chat, AI answers grounded in your knowledge base, and a help center. One provider at bootstrap, one script tag, isolated in a Shadow DOM.
+
+## Install
+
+```
+npm install @deskcrew/angular
+```
+
+Standalone apps, in `src/app/app.config.ts`:
+
+```ts
+import { ApplicationConfig } from '@angular/core'
+import { provideDeskcrew } from '@deskcrew/angular'
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideDeskcrew({ widgetKey: 'pub_your_widget_key', board: 'your-board' })],
+}
+```
+
+NgModule apps: add the same `provideDeskcrew(...)` to the `providers` array of `AppModule`.
+
+Prefer no code at all? Paste the tag from `buildTag(options).tag` into `src/index.html` before `</body>`; the provider does the same thing when the app boots.
+
+Get the key from the Install page of your DeskCrew dashboard. With Angular SSR the server render does nothing and the browser bootstrap injects the widget.
+
+## 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,21 @@
+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 { Provider } from '@angular/core'
+
+/** Injects the widget <script> into the document once. Returns false when the key is invalid or without a DOM. */
+export function injectDeskcrew(options: DeskcrewOptions): boolean
+/** APP_INITIALIZER provider that injects the widget at bootstrap. */
+export function provideDeskcrew(options: DeskcrewOptions): Provider
+export default provideDeskcrew
+export function buildTag(options: DeskcrewOptions): { tag: string | null; warnings: string[] }

package/index.js

@@ -0,0 +1,39 @@
+import { APP_INITIALIZER } from '@angular/core'
+import { buildAttrs } from './build-tag.js'
+
+/** Add the widget <script> to the document once. Safe to call more than once. No-op without a DOM. */
+export function injectDeskcrew(options) {
+  if (typeof document === 'undefined') return false
+  const { attrs, warnings } = buildAttrs(options)
+  for (const message of warnings) console.warn(message)
+  if (!attrs) return false
+  if (document.querySelector('script[src="https://deskcrew.io/desk.js"]')) return true
+  const s = document.createElement('script')
+  for (const [name, value] of attrs) {
+    if (name === 'src') s.src = value
+    else s.setAttribute(name, value)
+  }
+  s.defer = true
+  document.head.appendChild(s)
+  return true
+}
+
+/**
+ * providers: [provideDeskcrew({ widgetKey: 'pub_...' })] in app.config.ts
+ * (standalone) or in your root NgModule. Injects the widget when the app
+ * bootstraps in the browser; with Angular SSR the server does nothing.
+ *
+ * @param {import('./index.js').DeskcrewOptions} options
+ */
+export function provideDeskcrew(options) {
+  return {
+    provide: APP_INITIALIZER,
+    multi: true,
+    useFactory: () => () => {
+      injectDeskcrew(options)
+    },
+  }
+}
+
+export default provideDeskcrew
+export { buildTag } from './build-tag.js'

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@deskcrew/angular",
+  "version": "1.0.0",
+  "description": "Angular provider that adds the DeskCrew support widget (live chat, AI answers from your knowledge base, a help center) to your app at bootstrap.",
+  "keywords": [
+    "angular",
+    "angular2",
+    "ng",
+    "angular-library",
+    "standalone",
+    "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/angular-deskcrew.git"
+  },
+  "homepage": "https://deskcrew.io/integrations/angular",
+  "bugs": {
+    "url": "https://github.com/webmilmind1/angular-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"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=15"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}