@beeport/widget 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -34,6 +34,7 @@ function init(config) {
     throw new Error("BeePort widget requires a browser environment");
   }
   if (window.__beeport_loaded) return;
+  if (document.querySelector(`script[${SCRIPT_ATTR}]`)) return;
   const script = document.createElement("script");
   script.src = CDN_URL;
   script.setAttribute(SCRIPT_ATTR, "true");
@@ -51,11 +52,9 @@ function init(config) {
     script.setAttribute("data-text", config.text);
   }
   document.body.appendChild(script);
-  window.__beeport_loaded = true;
 }
 function destroy() {
   if (typeof window === "undefined") return;
-  window.dispatchEvent(new CustomEvent("beeport:destroy"));
   document.body.querySelectorAll(`script[${SCRIPT_ATTR}]`).forEach((el) => el.remove());
   document.body.querySelectorAll("[data-beeport-trigger]").forEach((el) => el.remove());
   document.body.querySelectorAll("[data-beeport-card]").forEach((el) => el.remove());

package/dist/index.js

@@ -6,6 +6,7 @@ function init(config) {
     throw new Error("BeePort widget requires a browser environment");
   }
   if (window.__beeport_loaded) return;
+  if (document.querySelector(`script[${SCRIPT_ATTR}]`)) return;
   const script = document.createElement("script");
   script.src = CDN_URL;
   script.setAttribute(SCRIPT_ATTR, "true");
@@ -23,11 +24,9 @@ function init(config) {
     script.setAttribute("data-text", config.text);
   }
   document.body.appendChild(script);
-  window.__beeport_loaded = true;
 }
 function destroy() {
   if (typeof window === "undefined") return;
-  window.dispatchEvent(new CustomEvent("beeport:destroy"));
   document.body.querySelectorAll(`script[${SCRIPT_ATTR}]`).forEach((el) => el.remove());
   document.body.querySelectorAll("[data-beeport-trigger]").forEach((el) => el.remove());
   document.body.querySelectorAll("[data-beeport-card]").forEach((el) => el.remove());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beeport/widget",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "BeePort feedback widget — npm package wrapper around CDN widget.js",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -13,19 +13,11 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
   "sideEffects": false,
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "prepack": "npm run build"
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -39,5 +31,8 @@
     "feedback",
     "widget"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "UNLICENSED"
 }

package/src/index.ts

@@ -0,0 +1,161 @@
+/**
+ * @beeport/widget
+ *
+ * npm package wrapper around the CDN-served BeePort widget.
+ *
+ * Usage:
+ *   import { init } from '@beeport/widget';
+ *   init({ project: 'prj_abc123' });
+ *
+ * SSR-safe: no window/document access at module import time.
+ * All browser APIs are only accessed inside function bodies.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BeePortConfig {
+  /** Project API key (required). */
+  project: string;
+  /** Colour theme forwarded to the widget iframe. */
+  theme?: "light" | "dark" | "auto";
+  /** Position of the floating button. */
+  position?: "bottom-right" | "bottom-left";
+  /** Custom accent colour (any CSS colour string). */
+  accent?: string;
+  /** Custom button label text. */
+  text?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CDN_URL = "https://cdn.beeport.ai/widget.js";
+const SCRIPT_ATTR = "data-beeport-script";
+
+// ---------------------------------------------------------------------------
+// Exported API
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and initialise the BeePort widget by injecting the CDN script tag.
+ *
+ * Idempotent — calling init() multiple times is safe; the second call is a
+ * no-op if the widget is already loaded.
+ *
+ * @throws Error if called in a non-browser environment (SSR guard).
+ */
+export function init(config: BeePortConfig): void {
+  if (typeof window === "undefined") {
+    throw new Error("BeePort widget requires a browser environment");
+  }
+
+  // Deduplication guard — check both the loaded flag (set by CDN script after
+  // init) and whether we've already injected the script tag (covers the window
+  // between injection and CDN script execution).
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  if ((window as any).__beeport_loaded) return;
+  if (document.querySelector(`script[${SCRIPT_ATTR}]`)) return;
+
+  const script = document.createElement("script");
+  script.src = CDN_URL;
+  script.setAttribute(SCRIPT_ATTR, "true");
+  script.setAttribute("data-project", config.project);
+
+  if (config.theme !== undefined) {
+    script.setAttribute("data-theme", config.theme);
+  }
+  if (config.position !== undefined) {
+    script.setAttribute("data-position", config.position);
+  }
+  if (config.accent !== undefined) {
+    script.setAttribute("data-accent", config.accent);
+  }
+  if (config.text !== undefined) {
+    script.setAttribute("data-text", config.text);
+  }
+
+  document.body.appendChild(script);
+}
+
+/**
+ * Remove all widget DOM elements and reset the loaded flag.
+ *
+ * After calling destroy(), init() can be called again to re-initialise.
+ * Safe to call before init() or in non-browser environments (no-op).
+ */
+export function destroy(): void {
+  if (typeof window === "undefined") return;
+
+  // Remove the injected script tag
+  document.body
+    .querySelectorAll(`script[${SCRIPT_ATTR}]`)
+    .forEach((el) => el.remove());
+
+  // Remove floating trigger button
+  document.body
+    .querySelectorAll("[data-beeport-trigger]")
+    .forEach((el) => el.remove());
+
+  // Remove desktop card
+  document.body
+    .querySelectorAll("[data-beeport-card]")
+    .forEach((el) => el.remove());
+
+  // Remove mobile bottom sheet
+  document.body
+    .querySelectorAll("[data-beeport-sheet]")
+    .forEach((el) => el.remove());
+
+  // Reset deduplication flag so init() can run again
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  delete (window as any).__beeport_loaded;
+}
+
+/**
+ * Programmatically open the feedback widget.
+ *
+ * Dispatches a `beeport:open` custom event on window. The loaded widget
+ * listens for this event and opens the iframe panel.
+ *
+ * Safe to call in non-browser environments (no-op).
+ */
+export function open(): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("beeport:open"));
+}
+
+/**
+ * Programmatically close the feedback widget.
+ *
+ * Dispatches a `beeport:close` custom event on window. The loaded widget
+ * listens for this event and closes the iframe panel.
+ *
+ * Safe to call in non-browser environments (no-op).
+ */
+export function close(): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("beeport:close"));
+}
+
+// ---------------------------------------------------------------------------
+// BeeportWidget namespace (default export)
+//
+// Provides BeeportWidget.init() usage pattern in addition to named exports.
+// Both patterns use the same underlying functions — no duplication.
+//
+// ESM: import BeeportWidget from '@beeport/widget'
+// CJS: const BeeportWidget = require('@beeport/widget').default
+// ---------------------------------------------------------------------------
+
+/**
+ * BeeportWidget namespace — use this for the BeeportWidget.init() call pattern.
+ *
+ * All methods are identical to the named exports and are tree-shakeable when
+ * destructured (e.g. `const { init } = BeeportWidget`).
+ */
+const BeeportWidget = { init, destroy, open, close } as const;
+
+export default BeeportWidget;

package/test/index.test.ts

@@ -0,0 +1,388 @@
+/**
+ * Tests for @beeport/widget npm package.
+ *
+ * Covers:
+ * - SSR safety: no window/document access at import time
+ * - init(): script tag injection, config attributes, deduplication guard
+ * - destroy(): removes script tag and widget elements
+ * - open() / close(): dispatches custom events
+ * - TypeScript types (compile-time, verified by import shape)
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import BeeportWidget, { init, destroy, open, close, type BeePortConfig } from "../src/index.js";
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  document.body.replaceChildren();
+  document.head.replaceChildren();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  delete (window as any).__beeport_loaded;
+});
+
+afterEach(() => {
+  document.body.replaceChildren();
+  document.head.replaceChildren();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  delete (window as any).__beeport_loaded;
+});
+
+// ---------------------------------------------------------------------------
+// SSR safety
+// ---------------------------------------------------------------------------
+
+describe("SSR safety", () => {
+  it("module exports init, destroy, open, close functions", () => {
+    // If import itself accessed window/document it would throw in Node.
+    // Since we are running in jsdom this verifies the shape at minimum.
+    expect(typeof init).toBe("function");
+    expect(typeof destroy).toBe("function");
+    expect(typeof open).toBe("function");
+    expect(typeof close).toBe("function");
+  });
+
+  it("init() throws a descriptive error when window is undefined", () => {
+    // Simulate SSR by temporarily removing window
+    const original = global.window;
+    // @ts-expect-error — intentionally deleting window for SSR test
+    delete global.window;
+
+    expect(() => init({ project: "prj_abc" })).toThrow(
+      "BeePort widget requires a browser environment"
+    );
+
+    // Restore window
+    global.window = original;
+  });
+});
+
+// ---------------------------------------------------------------------------
+// init()
+// ---------------------------------------------------------------------------
+
+describe("init()", () => {
+  it("injects a <script> tag into document.body", () => {
+    init({ project: "prj_abc" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script).not.toBeNull();
+  });
+
+  it("script src points to the CDN widget URL", () => {
+    init({ project: "prj_abc" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.src).toBe("https://cdn.beeport.ai/widget.js");
+  });
+
+  it("sets data-project attribute on the script tag", () => {
+    init({ project: "prj_test123" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.getAttribute("data-project")).toBe("prj_test123");
+  });
+
+  it("sets data-theme attribute when provided", () => {
+    init({ project: "prj_abc", theme: "dark" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.getAttribute("data-theme")).toBe("dark");
+  });
+
+  it("does not set data-theme when not provided", () => {
+    init({ project: "prj_abc" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.hasAttribute("data-theme")).toBe(false);
+  });
+
+  it("sets data-position when provided", () => {
+    init({ project: "prj_abc", position: "bottom-left" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.getAttribute("data-position")).toBe("bottom-left");
+  });
+
+  it("does not set data-position when not provided", () => {
+    init({ project: "prj_abc" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.hasAttribute("data-position")).toBe(false);
+  });
+
+  it("sets data-accent when provided", () => {
+    init({ project: "prj_abc", accent: "#ff0000" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.getAttribute("data-accent")).toBe("#ff0000");
+  });
+
+  it("does not set data-accent when not provided", () => {
+    init({ project: "prj_abc" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.hasAttribute("data-accent")).toBe(false);
+  });
+
+  it("sets data-text when provided", () => {
+    init({ project: "prj_abc", text: "Feedback" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.getAttribute("data-text")).toBe("Feedback");
+  });
+
+  it("does not set data-text when not provided", () => {
+    init({ project: "prj_abc" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script?.hasAttribute("data-text")).toBe(false);
+  });
+
+  it("does not set window.__beeport_loaded (CDN script sets it after actual init)", () => {
+    init({ project: "prj_abc" });
+    // The NPM wrapper no longer sets __beeport_loaded — the CDN widget.js
+    // sets it after creating the button. This avoids a race condition where
+    // the flag blocks the CDN script's autoInit.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((window as any).__beeport_loaded).toBeUndefined();
+  });
+
+  it("does not inject a second script if already loaded", () => {
+    init({ project: "prj_abc" });
+    init({ project: "prj_abc" });
+    const scripts = document.body.querySelectorAll("script[data-beeport-script]");
+    expect(scripts).toHaveLength(1);
+  });
+
+  it("returns early if __beeport_loaded is pre-set", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (window as any).__beeport_loaded = true;
+    init({ project: "prj_abc" });
+    const scripts = document.body.querySelectorAll("script[data-beeport-script]");
+    expect(scripts).toHaveLength(0);
+  });
+
+  it("accepts all optional config fields without throwing", () => {
+    const config: BeePortConfig = {
+      project: "prj_abc",
+      theme: "auto",
+      position: "bottom-right",
+      accent: "#333333",
+      text: "Send feedback",
+    };
+    expect(() => init(config)).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// destroy()
+// ---------------------------------------------------------------------------
+
+describe("destroy()", () => {
+  it("removes the injected script tag", () => {
+    init({ project: "prj_abc" });
+    destroy();
+    const script = document.body.querySelector("script[data-beeport-script]");
+    expect(script).toBeNull();
+  });
+
+  it("resets the __beeport_loaded flag", () => {
+    init({ project: "prj_abc" });
+    destroy();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((window as any).__beeport_loaded).toBeUndefined();
+  });
+
+  it("removes the floating button element if present", () => {
+    init({ project: "prj_abc" });
+    // Simulate widget creating a button
+    const btn = document.createElement("button");
+    btn.setAttribute("data-beeport-trigger", "true");
+    document.body.appendChild(btn);
+    destroy();
+    const remaining = document.body.querySelector("[data-beeport-trigger]");
+    expect(remaining).toBeNull();
+  });
+
+  it("removes any iframe card if open", () => {
+    init({ project: "prj_abc" });
+    // Simulate an open card
+    const card = document.createElement("div");
+    card.setAttribute("data-beeport-card", "true");
+    document.body.appendChild(card);
+    destroy();
+    const remaining = document.body.querySelector("[data-beeport-card]");
+    expect(remaining).toBeNull();
+  });
+
+  it("removes any mobile sheet if open", () => {
+    init({ project: "prj_abc" });
+    const sheet = document.createElement("div");
+    sheet.setAttribute("data-beeport-sheet", "true");
+    document.body.appendChild(sheet);
+    destroy();
+    const remaining = document.body.querySelector("[data-beeport-sheet]");
+    expect(remaining).toBeNull();
+  });
+
+  it("does not throw when called before init", () => {
+    expect(() => destroy()).not.toThrow();
+  });
+
+  it("does not throw when window is undefined", () => {
+    const original = global.window;
+    // @ts-expect-error — intentionally removing window for SSR test
+    delete global.window;
+    expect(() => destroy()).not.toThrow();
+    global.window = original;
+  });
+
+  it("allows re-initialisation after destroy", () => {
+    init({ project: "prj_abc" });
+    destroy();
+    init({ project: "prj_abc" });
+    const script = document.body.querySelector("script[data-beeport-script]");
+    expect(script).not.toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// open()
+// ---------------------------------------------------------------------------
+
+describe("open()", () => {
+  it("dispatches a beeport:open custom event on window", () => {
+    const events: Event[] = [];
+    window.addEventListener("beeport:open", (e) => events.push(e));
+
+    open();
+
+    expect(events).toHaveLength(1);
+    window.removeEventListener("beeport:open", (e) => events.push(e));
+  });
+
+  it("does not throw when window is undefined", () => {
+    const original = global.window;
+    // @ts-expect-error — intentionally removing window
+    delete global.window;
+    expect(() => open()).not.toThrow();
+    global.window = original;
+  });
+});
+
+// ---------------------------------------------------------------------------
+// close()
+// ---------------------------------------------------------------------------
+
+describe("close()", () => {
+  it("dispatches a beeport:close custom event on window", () => {
+    const events: Event[] = [];
+    window.addEventListener("beeport:close", (e) => events.push(e));
+
+    close();
+
+    expect(events).toHaveLength(1);
+    window.removeEventListener("beeport:close", (e) => events.push(e));
+  });
+
+  it("does not throw when window is undefined", () => {
+    const original = global.window;
+    // @ts-expect-error — intentionally removing window
+    delete global.window;
+    expect(() => close()).not.toThrow();
+    global.window = original;
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BeeportWidget namespace export (default export)
+// ---------------------------------------------------------------------------
+
+describe("BeeportWidget namespace (default export)", () => {
+  it("exports a BeeportWidget object with init method", () => {
+    expect(typeof BeeportWidget).toBe("object");
+    expect(typeof BeeportWidget.init).toBe("function");
+  });
+
+  it("BeeportWidget.init() injects a <script> tag into document.body", () => {
+    BeeportWidget.init({ project: "prj_ns_test" });
+    const script = document.body.querySelector<HTMLScriptElement>(
+      "script[data-beeport-script]"
+    );
+    expect(script).not.toBeNull();
+    expect(script?.getAttribute("data-project")).toBe("prj_ns_test");
+  });
+
+  it("BeeportWidget.destroy() removes widget elements", () => {
+    BeeportWidget.init({ project: "prj_ns_test" });
+    BeeportWidget.destroy();
+    const script = document.body.querySelector("script[data-beeport-script]");
+    expect(script).toBeNull();
+  });
+
+  it("BeeportWidget.open() dispatches beeport:open event", () => {
+    const events: Event[] = [];
+    window.addEventListener("beeport:open", (e) => events.push(e));
+    BeeportWidget.open();
+    expect(events).toHaveLength(1);
+    window.removeEventListener("beeport:open", (e) => events.push(e));
+  });
+
+  it("BeeportWidget.close() dispatches beeport:close event", () => {
+    const events: Event[] = [];
+    window.addEventListener("beeport:close", (e) => events.push(e));
+    BeeportWidget.close();
+    expect(events).toHaveLength(1);
+    window.removeEventListener("beeport:close", (e) => events.push(e));
+  });
+
+  it("BeeportWidget.init() is identical to named init()", () => {
+    // Both should be the same function reference
+    expect(BeeportWidget.init).toBe(init);
+    expect(BeeportWidget.destroy).toBe(destroy);
+    expect(BeeportWidget.open).toBe(open);
+    expect(BeeportWidget.close).toBe(close);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TypeScript type validation (compile-time only — these just need to compile)
+// ---------------------------------------------------------------------------
+
+describe("TypeScript types", () => {
+  it("BeePortConfig requires project field", () => {
+    // This is a type-level test — just verifying config shape at runtime
+    const config: BeePortConfig = { project: "prj_required" };
+    expect(config.project).toBe("prj_required");
+  });
+
+  it("BeePortConfig theme accepts light | dark | auto", () => {
+    const light: BeePortConfig = { project: "p", theme: "light" };
+    const dark: BeePortConfig = { project: "p", theme: "dark" };
+    const auto: BeePortConfig = { project: "p", theme: "auto" };
+    expect(light.theme).toBe("light");
+    expect(dark.theme).toBe("dark");
+    expect(auto.theme).toBe("auto");
+  });
+
+  it("BeePortConfig position accepts bottom-right | bottom-left", () => {
+    const right: BeePortConfig = { project: "p", position: "bottom-right" };
+    const left: BeePortConfig = { project: "p", position: "bottom-left" };
+    expect(right.position).toBe("bottom-right");
+    expect(left.position).toBe("bottom-left");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationDir": "dist",
+    "types": ["node"]
+  },
+  "include": ["src/**/*", "test/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    globals: false,
+    include: ["test/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+    },
+  },
+});