@perspective-ai/sdk 1.0.0-alpha.2

package/src/browser.ts

@@ -0,0 +1,509 @@
+/**
+ * Perspective Embed SDK - Browser Entry
+ *
+ * CDN/Script Tag Entry Point - auto-init, attaches to window.Perspective
+ *
+ * Usage:
+ *   <script src="https://getperspective.ai/v1/perspective.js"></script>
+ *
+ *   <!-- Auto-init with data attributes -->
+ *   <div data-perspective-widget="research_xxx"></div>
+ *   <button data-perspective-popup="research_xxx">Open Survey</button>
+ *
+ *   <!-- Or programmatic -->
+ *   <script>
+ *     Perspective.openPopup({ researchId: 'xxx' });
+ *   </script>
+ */
+
+import type {
+  BrandColors,
+  EmbedConfig,
+  EmbedHandle,
+  FloatHandle,
+  ThemeConfig,
+} from "./types";
+import { DATA_ATTRS, THEME_VALUES } from "./constants";
+import { createWidget } from "./widget";
+import { openPopup } from "./popup";
+import { openSlider } from "./slider";
+import { createFloatBubble, createChatBubble } from "./float";
+import { createFullpage } from "./fullpage";
+import { configure, getConfig, hasDom, getHost } from "./config";
+import { resolveIsDark } from "./utils";
+
+// Track all active instances
+const instances: Map<string, EmbedHandle | FloatHandle> = new Map();
+
+// Theme config cache
+const configCache: Map<string, ThemeConfig> = new Map();
+
+type ButtonStyleConfig = {
+  themeConfig: ThemeConfig;
+  theme?: EmbedConfig["theme"];
+  brand?: EmbedConfig["brand"];
+};
+const styledButtons = new Map<HTMLElement, ButtonStyleConfig>();
+let buttonThemeMediaQuery: MediaQueryList | null = null;
+
+const DEFAULT_THEME: ThemeConfig = {
+  primaryColor: "#7c3aed",
+  textColor: "#ffffff",
+  darkPrimaryColor: "#a78bfa",
+  darkTextColor: "#ffffff",
+};
+
+/**
+ * Fetch theme config from API (cached)
+ */
+async function fetchConfig(researchId: string): Promise<ThemeConfig> {
+  if (configCache.has(researchId)) {
+    return configCache.get(researchId)!;
+  }
+
+  try {
+    const host = getHost();
+    const res = await fetch(`${host}/api/v1/embed/config/${researchId}`);
+    if (!res.ok) return DEFAULT_THEME;
+    const config = await res.json();
+    configCache.set(researchId, config);
+    return config;
+  } catch {
+    return DEFAULT_THEME;
+  }
+}
+
+/**
+ * Apply theme styles to a button element
+ */
+function styleButton(
+  el: HTMLElement,
+  themeConfig: ThemeConfig,
+  options?: { theme?: EmbedConfig["theme"]; brand?: EmbedConfig["brand"] }
+): void {
+  if (el.hasAttribute(DATA_ATTRS.noStyle)) return;
+
+  styledButtons.set(el, {
+    themeConfig,
+    theme: options?.theme,
+    brand: options?.brand,
+  });
+
+  updateButtonTheme(el, {
+    themeConfig,
+    theme: options?.theme,
+    brand: options?.brand,
+  });
+}
+
+/**
+ * Update button styles based on theme
+ */
+function updateButtonTheme(el: HTMLElement, config: ButtonStyleConfig): void {
+  const { themeConfig, theme, brand } = config;
+  const isDark = resolveIsDark(theme);
+
+  const bg = isDark
+    ? (brand?.dark?.primary ?? themeConfig.darkPrimaryColor)
+    : (brand?.light?.primary ?? themeConfig.primaryColor);
+  const text = isDark
+    ? (brand?.dark?.text ?? themeConfig.darkTextColor)
+    : (brand?.light?.text ?? themeConfig.textColor);
+
+  el.style.backgroundColor = bg;
+  el.style.color = text;
+  el.style.padding = "10px 20px";
+  el.style.border = "none";
+  el.style.borderRadius = "8px";
+  el.style.fontWeight = "500";
+  el.style.cursor = "pointer";
+}
+
+/**
+ * Update all styled buttons when theme changes
+ */
+function updateAllButtonThemes(): void {
+  styledButtons.forEach((config, el) => {
+    if (document.contains(el)) {
+      updateButtonTheme(el, config);
+    } else {
+      styledButtons.delete(el);
+    }
+  });
+}
+
+let buttonThemeListener: ((e: MediaQueryListEvent) => void) | null = null;
+
+function setupButtonThemeListener(): void {
+  if (buttonThemeListener || !hasDom()) return;
+
+  buttonThemeMediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+  buttonThemeListener = () => updateAllButtonThemes();
+  buttonThemeMediaQuery.addEventListener("change", buttonThemeListener);
+}
+
+function teardownButtonThemeListener(): void {
+  if (buttonThemeListener && buttonThemeMediaQuery) {
+    buttonThemeMediaQuery.removeEventListener("change", buttonThemeListener);
+    buttonThemeListener = null;
+    buttonThemeMediaQuery = null;
+  }
+}
+
+/**
+ * Parse params from data attribute (format: "key1=value1,key2=value2")
+ */
+function parseParamsAttr(el: HTMLElement): Record<string, string> | undefined {
+  const paramsStr = el.getAttribute(DATA_ATTRS.params);
+  if (!paramsStr) return undefined;
+
+  const params: Record<string, string> = {};
+  for (const pair of paramsStr.split(",")) {
+    const [key, ...valueParts] = pair.trim().split("=");
+    if (key) {
+      params[key.trim()] = valueParts.join("=").trim();
+    }
+  }
+  return Object.keys(params).length > 0 ? params : undefined;
+}
+
+/**
+ * Parse brand colors from data attribute (format: "primary=#xxx,bg=#yyy")
+ */
+function parseBrandAttr(attrValue: string | null): BrandColors | undefined {
+  if (!attrValue) return undefined;
+
+  const colors: BrandColors = {};
+  for (const pair of attrValue.split(",")) {
+    const [key, ...valueParts] = pair.trim().split("=");
+    if (key && valueParts.length > 0) {
+      const value = valueParts.join("=").trim();
+      if (value) {
+        const k = key.trim() as keyof BrandColors;
+        if (
+          k === "primary" ||
+          k === "secondary" ||
+          k === "bg" ||
+          k === "text"
+        ) {
+          colors[k] = value;
+        }
+      }
+    }
+  }
+  return Object.keys(colors).length > 0 ? colors : undefined;
+}
+
+/**
+ * Extract brand config and theme from element attributes
+ */
+function extractBrandConfig(
+  el: HTMLElement
+): Pick<EmbedConfig, "brand" | "theme"> {
+  const light = parseBrandAttr(el.getAttribute(DATA_ATTRS.brand));
+  const dark = parseBrandAttr(el.getAttribute(DATA_ATTRS.brandDark));
+  const themeAttr = el.getAttribute(DATA_ATTRS.theme);
+
+  const config: Pick<EmbedConfig, "brand" | "theme"> = {};
+
+  if (light || dark) {
+    config.brand = {};
+    if (light) config.brand.light = light;
+    if (dark) config.brand.dark = dark;
+  }
+
+  if (
+    themeAttr === THEME_VALUES.dark ||
+    themeAttr === THEME_VALUES.light ||
+    themeAttr === THEME_VALUES.system
+  ) {
+    config.theme = themeAttr;
+  }
+
+  return config;
+}
+
+/**
+ * Initialize an embed programmatically
+ */
+function init(config: EmbedConfig): EmbedHandle | FloatHandle {
+  const { researchId } = config;
+  // Normalize legacy "chat" type to "float"
+  const type = config.type === "chat" ? "float" : (config.type ?? "widget");
+
+  // Destroy existing instance for this research
+  if (instances.has(researchId)) {
+    instances.get(researchId)!.unmount();
+    instances.delete(researchId);
+  }
+
+  let instance: EmbedHandle | FloatHandle;
+
+  switch (type) {
+    case "popup":
+      instance = openPopup(config);
+      break;
+    case "slider":
+      instance = openSlider(config);
+      break;
+    case "float":
+      instance = createFloatBubble(config);
+      break;
+    case "fullpage":
+      instance = createFullpage(config);
+      break;
+    default:
+      throw new Error(
+        `Unknown embed type "${type}". Valid types: popup, slider, float, fullpage (use init()), or widget (use mount()).`
+      );
+  }
+
+  instances.set(researchId, instance);
+  return instance;
+}
+
+/**
+ * Mount a widget into a container element
+ */
+function mount(
+  container: HTMLElement | string,
+  config: EmbedConfig
+): EmbedHandle {
+  const { researchId } = config;
+  const type = config.type === "chat" ? "float" : (config.type ?? "widget");
+
+  const el =
+    typeof container === "string"
+      ? document.querySelector<HTMLElement>(container)
+      : container;
+
+  if (!el) {
+    throw new Error(`Container not found: ${container}`);
+  }
+
+  // Destroy existing instance
+  if (instances.has(researchId)) {
+    instances.get(researchId)!.unmount();
+    instances.delete(researchId);
+  }
+
+  let instance: EmbedHandle;
+
+  switch (type) {
+    case "widget":
+      instance = createWidget(el, config);
+      break;
+    default:
+      // For popup/slider/float, just use init - container not used
+      instance = init({ ...config, type }) as EmbedHandle;
+      return instance;
+  }
+
+  instances.set(researchId, instance);
+  return instance;
+}
+
+/**
+ * Destroy an embed instance
+ */
+function destroy(researchId: string): void {
+  const instance = instances.get(researchId);
+  if (instance) {
+    instance.unmount();
+    instances.delete(researchId);
+  }
+}
+
+function destroyAll(): void {
+  instances.forEach((instance) => instance.unmount());
+  instances.clear();
+  styledButtons.clear();
+  teardownButtonThemeListener();
+}
+
+/**
+ * Auto-initialize embeds from data attributes
+ */
+function autoInit(): void {
+  if (!hasDom()) return;
+
+  setupButtonThemeListener();
+
+  // Widget embeds
+  document
+    .querySelectorAll<HTMLElement>(`[${DATA_ATTRS.widget}]`)
+    .forEach((el) => {
+      const researchId = el.getAttribute(DATA_ATTRS.widget);
+      if (researchId && !instances.has(researchId)) {
+        const params = parseParamsAttr(el);
+        const brandConfig = extractBrandConfig(el);
+        mount(el, { researchId, type: "widget", params, ...brandConfig });
+      }
+    });
+
+  // Fullpage embeds
+  document
+    .querySelectorAll<HTMLElement>(`[${DATA_ATTRS.fullpage}]`)
+    .forEach((el) => {
+      const researchId = el.getAttribute(DATA_ATTRS.fullpage);
+      if (researchId && !instances.has(researchId)) {
+        const params = parseParamsAttr(el);
+        const brandConfig = extractBrandConfig(el);
+        init({ researchId, type: "fullpage", params, ...brandConfig });
+      }
+    });
+
+  // Popup triggers
+  document
+    .querySelectorAll<HTMLElement>(`[${DATA_ATTRS.popup}]`)
+    .forEach((el) => {
+      if (el.hasAttribute("data-perspective-initialized")) return;
+      el.setAttribute("data-perspective-initialized", "true");
+
+      const researchId = el.getAttribute(DATA_ATTRS.popup);
+      if (researchId) {
+        const params = parseParamsAttr(el);
+        const brandConfig = extractBrandConfig(el);
+        styleButton(el, DEFAULT_THEME, brandConfig);
+        el.addEventListener("click", (e) => {
+          e.preventDefault();
+          init({ researchId, type: "popup", params, ...brandConfig });
+        });
+        fetchConfig(researchId).then((config) => {
+          styleButton(el, config, brandConfig);
+        });
+      }
+    });
+
+  // Slider triggers
+  document
+    .querySelectorAll<HTMLElement>(`[${DATA_ATTRS.slider}]`)
+    .forEach((el) => {
+      if (el.hasAttribute("data-perspective-initialized")) return;
+      el.setAttribute("data-perspective-initialized", "true");
+
+      const researchId = el.getAttribute(DATA_ATTRS.slider);
+      if (researchId) {
+        const params = parseParamsAttr(el);
+        const brandConfig = extractBrandConfig(el);
+        styleButton(el, DEFAULT_THEME, brandConfig);
+        el.addEventListener("click", (e) => {
+          e.preventDefault();
+          init({ researchId, type: "slider", params, ...brandConfig });
+        });
+        fetchConfig(researchId).then((config) => {
+          styleButton(el, config, brandConfig);
+        });
+      }
+    });
+
+  // Float bubble - supports both data-perspective-float and data-perspective-chat (legacy)
+  const floatSelector = `[${DATA_ATTRS.float}], [${DATA_ATTRS.chat}]`;
+  const floatEl = document.querySelector<HTMLElement>(floatSelector);
+  if (floatEl) {
+    const researchId =
+      floatEl.getAttribute(DATA_ATTRS.float) ||
+      floatEl.getAttribute(DATA_ATTRS.chat);
+    if (researchId && !instances.has(researchId)) {
+      const params = parseParamsAttr(floatEl);
+      const brandConfig = extractBrandConfig(floatEl);
+      init({
+        researchId,
+        type: "float",
+        params,
+        ...brandConfig,
+        _themeConfig: DEFAULT_THEME,
+      } as EmbedConfig & { _themeConfig: ThemeConfig });
+
+      fetchConfig(researchId).then((config) => {
+        // Update bubble color with fetched theme
+        const bubble = document.querySelector<HTMLElement>(
+          '[data-perspective="float-bubble"]'
+        );
+        if (bubble && !floatEl.hasAttribute(DATA_ATTRS.noStyle)) {
+          const isDark = resolveIsDark(brandConfig.theme);
+          const bg = isDark
+            ? (brandConfig.brand?.dark?.primary ?? config.darkPrimaryColor)
+            : (brandConfig.brand?.light?.primary ?? config.primaryColor);
+          bubble.style.setProperty("--perspective-float-bg", bg);
+          bubble.style.setProperty(
+            "--perspective-float-shadow",
+            `0 4px 12px ${bg}66`
+          );
+          bubble.style.setProperty(
+            "--perspective-float-shadow-hover",
+            `0 6px 16px ${bg}80`
+          );
+          bubble.style.backgroundColor = bg;
+          bubble.style.boxShadow = `0 4px 12px ${bg}66`;
+        }
+      });
+    }
+  }
+}
+
+// Build the public API
+const Perspective = {
+  // Configuration
+  configure,
+  getConfig,
+
+  // Instance management
+  init,
+  mount,
+  destroy,
+  destroyAll,
+  autoInit,
+
+  // Direct creation functions (primary API)
+  createWidget,
+  openPopup,
+  openSlider,
+  createFloatBubble,
+  createFullpage,
+
+  // Legacy alias
+  createChatBubble,
+};
+
+declare global {
+  interface Window {
+    __PERSPECTIVE_SDK_INITIALIZED__?: boolean;
+    Perspective?: typeof Perspective;
+  }
+}
+
+// Prevent duplicate initialization when script is loaded multiple times
+// (e.g., SPAs, tag managers, hot-reload, or accidental double-include).
+// Without this guard, each script evaluation would register new listeners
+// and create isolated module state, causing memory leaks and duplicate handlers.
+if (hasDom() && !window.__PERSPECTIVE_SDK_INITIALIZED__) {
+  window.__PERSPECTIVE_SDK_INITIALIZED__ = true;
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", autoInit, { once: true });
+  } else {
+    autoInit();
+  }
+
+  window.Perspective = Perspective;
+}
+
+// Export for module usage
+export {
+  configure,
+  getConfig,
+  init,
+  mount,
+  destroy,
+  destroyAll,
+  autoInit,
+  createWidget,
+  openPopup,
+  openSlider,
+  createFloatBubble,
+  createChatBubble,
+  createFullpage,
+};
+
+export default Perspective;

package/src/config.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+
+describe("config", () => {
+  let configure: typeof import("./config").configure;
+  let getConfig: typeof import("./config").getConfig;
+  let hasDom: typeof import("./config").hasDom;
+  let getHost: typeof import("./config").getHost;
+
+  beforeEach(async () => {
+    // Reset module state between tests to avoid state leakage
+    vi.resetModules();
+    const configModule = await import("./config");
+    configure = configModule.configure;
+    getConfig = configModule.getConfig;
+    hasDom = configModule.hasDom;
+    getHost = configModule.getHost;
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("configure", () => {
+    it("sets global config", () => {
+      configure({ host: "https://example.com" });
+      expect(getConfig()).toEqual({ host: "https://example.com" });
+    });
+
+    it("merges with existing config", () => {
+      configure({ host: "https://example.com" });
+      configure({ host: "https://other.com" });
+      expect(getConfig()).toEqual({ host: "https://other.com" });
+    });
+  });
+
+  describe("getConfig", () => {
+    it("returns a copy of config", () => {
+      configure({ host: "https://example.com" });
+      const config1 = getConfig();
+      const config2 = getConfig();
+      expect(config1).toEqual(config2);
+      expect(config1).not.toBe(config2); // Different object references
+    });
+  });
+
+  describe("hasDom", () => {
+    it("returns true when window and document exist", () => {
+      expect(hasDom()).toBe(true);
+    });
+  });
+
+  describe("getHost", () => {
+    it("returns instance host if provided", () => {
+      expect(getHost("https://instance.example.com")).toBe(
+        "https://instance.example.com"
+      );
+    });
+
+    it("normalizes URL to origin", () => {
+      expect(getHost("https://example.com/some/path?query=1")).toBe(
+        "https://example.com"
+      );
+    });
+
+    it("returns global config host if no instance host", () => {
+      configure({ host: "https://global.example.com" });
+      expect(getHost()).toBe("https://global.example.com");
+    });
+
+    it("instance host takes precedence over global", () => {
+      configure({ host: "https://global.example.com" });
+      expect(getHost("https://instance.example.com")).toBe(
+        "https://instance.example.com"
+      );
+    });
+
+    it("returns default host when no config", () => {
+      expect(getHost()).toBe("https://getperspective.ai");
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,95 @@
+/**
+ * Embed SDK configuration
+ * SSR-safe - DOM access is guarded and lazy
+ */
+
+import type { SDKConfig } from "./types";
+
+/** Default production host */
+const DEFAULT_HOST = "https://getperspective.ai";
+
+/** Global SDK configuration - can be set before creating embeds */
+let globalConfig: SDKConfig = {};
+
+/**
+ * Configure the SDK globally
+ * Call this before creating any embeds if you need to override defaults
+ */
+export function configure(config: SDKConfig): void {
+  globalConfig = { ...globalConfig, ...config };
+}
+
+/**
+ * Get the current SDK configuration
+ */
+export function getConfig(): SDKConfig {
+  return { ...globalConfig };
+}
+
+/**
+ * Check if DOM is available (SSR safety)
+ */
+export function hasDom(): boolean {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+
+function normalizeToOrigin(host: string): string {
+  try {
+    return new URL(host).origin;
+  } catch {
+    return host;
+  }
+}
+
+export function getHost(instanceHost?: string): string {
+  // Instance-level override
+  if (instanceHost) {
+    return normalizeToOrigin(instanceHost);
+  }
+
+  // Global config override
+  if (globalConfig.host) {
+    return normalizeToOrigin(globalConfig.host);
+  }
+
+  // Try to infer from script src (only in browser, only at load time)
+  if (hasDom()) {
+    const scriptHost = getScriptHost();
+    if (scriptHost) {
+      return scriptHost;
+    }
+  }
+
+  return DEFAULT_HOST;
+}
+
+// Capture script src at load time - document.currentScript only available during initial execution
+let capturedScriptHost: string | null = null;
+
+function getScriptHost(): string | null {
+  if (capturedScriptHost !== null) {
+    return capturedScriptHost;
+  }
+
+  if (!hasDom()) {
+    return null;
+  }
+
+  const currentScript = document.currentScript as HTMLScriptElement | null;
+  if (currentScript?.src) {
+    try {
+      capturedScriptHost = new URL(currentScript.src).origin;
+      return capturedScriptHost;
+    } catch {
+      // Invalid URL, ignore
+    }
+  }
+
+  capturedScriptHost = ""; // Mark as attempted
+  return null;
+}
+
+// Capture script host immediately when module loads (in browser)
+if (hasDom()) {
+  getScriptHost();
+}