@beeport/widget 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# @beeport/widget
+
+BeePort feedback widget — npm package for programmatic installation.
+
+Injects the same CDN-hosted widget as the `<script>` tag installation, but lets you control initialisation from your application code.
+
+## Installation
+
+```bash
+npm install @beeport/widget
+```
+
+## Usage
+
+### Named imports (recommended — tree-shakeable)
+
+```typescript
+import { init, destroy, open, close } from '@beeport/widget';
+
+// Initialise the widget
+init({ project: 'prj_abc123' });
+
+// Programmatically open/close the feedback panel
+open();
+close();
+
+// Remove all widget elements and reset (allows re-init)
+destroy();
+```
+
+### Namespace import
+
+```typescript
+import BeeportWidget from '@beeport/widget';
+
+BeeportWidget.init({ project: 'prj_abc123' });
+BeeportWidget.open();
+BeeportWidget.close();
+BeeportWidget.destroy();
+```
+
+### CommonJS
+
+```javascript
+const { init, destroy, open, close } = require('@beeport/widget');
+init({ project: 'prj_abc123' });
+```
+
+## API
+
+### `init(config)`
+
+Loads and initialises the BeePort widget by injecting the CDN script tag into `document.body`.
+
+Idempotent — calling `init()` multiple times is safe; subsequent calls are no-ops.
+
+**Throws** `Error` if called outside a browser environment (SSR guard).
+
+```typescript
+init({
+  project: 'prj_abc123',    // Required. Your project key.
+  theme: 'auto',            // Optional. 'light' | 'dark' | 'auto'. Default: browser default.
+  position: 'bottom-right', // Optional. 'bottom-right' | 'bottom-left'. Default: 'bottom-right'.
+  accent: '#f3c744',        // Optional. CSS colour string. Default: BeePort gold.
+  text: 'Feedback',         // Optional. Button label. Default: 'Feedback'.
+});
+```
+
+### `destroy()`
+
+Removes all widget DOM elements (script tag, trigger button, iframe card, mobile sheet) and resets the loaded flag so `init()` can be called again.
+
+Safe to call before `init()` or in non-browser environments (no-op).
+
+### `open()`
+
+Programmatically opens the feedback panel by dispatching a `beeport:open` custom event on `window`.
+
+Safe to call in non-browser environments (no-op).
+
+### `close()`
+
+Programmatically closes the feedback panel by dispatching a `beeport:close` custom event on `window`.
+
+Safe to call in non-browser environments (no-op).
+
+## TypeScript
+
+Full TypeScript types are included. The `BeePortConfig` interface is exported for use in your own code:
+
+```typescript
+import { init, type BeePortConfig } from '@beeport/widget';
+
+const config: BeePortConfig = {
+  project: 'prj_abc123',
+  theme: 'dark',
+};
+
+init(config);
+```
+
+## Framework examples
+
+### React
+
+```tsx
+import { useEffect } from 'react';
+import { init, destroy } from '@beeport/widget';
+
+export function FeedbackWidget() {
+  useEffect(() => {
+    init({ project: 'prj_abc123', theme: 'auto' });
+    return () => destroy();
+  }, []);
+
+  return null;
+}
+```
+
+### Vue
+
+```typescript
+import { onMounted, onUnmounted } from 'vue';
+import { init, destroy } from '@beeport/widget';
+
+export function useFeedbackWidget(project: string) {
+  onMounted(() => init({ project }));
+  onUnmounted(() => destroy());
+}
+```
+
+## SSR
+
+The package is SSR-safe. No `window` or `document` access occurs at import time — all browser APIs are only accessed inside function bodies. `init()` throws a descriptive error if called server-side; all other functions are silent no-ops.
+
+## Output formats
+
+- **ESM** (`dist/index.js`) — for bundlers and modern environments
+- **CJS** (`dist/index.cjs`) — for Node.js and legacy bundlers
+- **Types** (`dist/index.d.ts`) — TypeScript declarations
+
+`sideEffects: false` is set in `package.json` for reliable tree-shaking.
+
+## Script tag alternative
+
+If you don't use a bundler, load the widget directly from the CDN:
+
+```html
+<script
+  src="https://cdn.beeport.ai/widget.js"
+  data-project="prj_abc123"
+  data-theme="auto"
+></script>
+```

package/dist/index.cjs

@@ -0,0 +1,81 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  close: () => close,
+  default: () => index_default,
+  destroy: () => destroy,
+  init: () => init,
+  open: () => open
+});
+module.exports = __toCommonJS(index_exports);
+var CDN_URL = "https://cdn.beeport.ai/widget.js";
+var SCRIPT_ATTR = "data-beeport-script";
+function init(config) {
+  if (typeof window === "undefined") {
+    throw new Error("BeePort widget requires a browser environment");
+  }
+  if (window.__beeport_loaded) return;
+  const script = document.createElement("script");
+  script.src = CDN_URL;
+  script.setAttribute(SCRIPT_ATTR, "true");
+  script.setAttribute("data-project", config.project);
+  if (config.theme !== void 0) {
+    script.setAttribute("data-theme", config.theme);
+  }
+  if (config.position !== void 0) {
+    script.setAttribute("data-position", config.position);
+  }
+  if (config.accent !== void 0) {
+    script.setAttribute("data-accent", config.accent);
+  }
+  if (config.text !== void 0) {
+    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());
+  document.body.querySelectorAll("[data-beeport-sheet]").forEach((el) => el.remove());
+  delete window.__beeport_loaded;
+}
+function open() {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("beeport:open"));
+}
+function close() {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("beeport:close"));
+}
+var BeeportWidget = { init, destroy, open, close };
+var index_default = BeeportWidget;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  close,
+  destroy,
+  init,
+  open
+});

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+/**
+ * @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.
+ */
+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;
+}
+/**
+ * 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).
+ */
+declare function init(config: BeePortConfig): void;
+/**
+ * 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).
+ */
+declare function destroy(): void;
+/**
+ * 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).
+ */
+declare function open(): void;
+/**
+ * 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).
+ */
+declare function close(): void;
+/**
+ * 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`).
+ */
+declare const BeeportWidget: {
+    readonly init: typeof init;
+    readonly destroy: typeof destroy;
+    readonly open: typeof open;
+    readonly close: typeof close;
+};
+
+export { type BeePortConfig, close, BeeportWidget as default, destroy, init, open };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @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.
+ */
+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;
+}
+/**
+ * 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).
+ */
+declare function init(config: BeePortConfig): void;
+/**
+ * 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).
+ */
+declare function destroy(): void;
+/**
+ * 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).
+ */
+declare function open(): void;
+/**
+ * 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).
+ */
+declare function close(): void;
+/**
+ * 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`).
+ */
+declare const BeeportWidget: {
+    readonly init: typeof init;
+    readonly destroy: typeof destroy;
+    readonly open: typeof open;
+    readonly close: typeof close;
+};
+
+export { type BeePortConfig, close, BeeportWidget as default, destroy, init, open };

package/dist/index.js

@@ -0,0 +1,53 @@
+// src/index.ts
+var CDN_URL = "https://cdn.beeport.ai/widget.js";
+var SCRIPT_ATTR = "data-beeport-script";
+function init(config) {
+  if (typeof window === "undefined") {
+    throw new Error("BeePort widget requires a browser environment");
+  }
+  if (window.__beeport_loaded) return;
+  const script = document.createElement("script");
+  script.src = CDN_URL;
+  script.setAttribute(SCRIPT_ATTR, "true");
+  script.setAttribute("data-project", config.project);
+  if (config.theme !== void 0) {
+    script.setAttribute("data-theme", config.theme);
+  }
+  if (config.position !== void 0) {
+    script.setAttribute("data-position", config.position);
+  }
+  if (config.accent !== void 0) {
+    script.setAttribute("data-accent", config.accent);
+  }
+  if (config.text !== void 0) {
+    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());
+  document.body.querySelectorAll("[data-beeport-sheet]").forEach((el) => el.remove());
+  delete window.__beeport_loaded;
+}
+function open() {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("beeport:open"));
+}
+function close() {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("beeport:close"));
+}
+var BeeportWidget = { init, destroy, open, close };
+var index_default = BeeportWidget;
+export {
+  close,
+  index_default as default,
+  destroy,
+  init,
+  open
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@beeport/widget",
+  "version": "0.1.0",
+  "description": "BeePort feedback widget — npm package wrapper around CDN widget.js",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "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"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "jsdom": "^26.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "beeport",
+    "feedback",
+    "widget"
+  ],
+  "license": "UNLICENSED"
+}