@perspective-ai/sdk 1.0.0-alpha.2

package/src/float.ts

@@ -0,0 +1,231 @@
+/**
+ * Floating bubble embed - floating button that opens a chat window
+ * SSR-safe - returns no-op handle on server
+ */
+
+import type { EmbedConfig, FloatHandle, ThemeConfig } from "./types";
+import { hasDom, getHost } from "./config";
+import {
+  createIframe,
+  setupMessageListener,
+  registerIframe,
+  ensureGlobalListeners,
+} from "./iframe";
+import { createLoadingIndicator } from "./loading";
+import { injectStyles, MIC_ICON, CLOSE_ICON } from "./styles";
+import { cn, getThemeClass, resolveIsDark } from "./utils";
+
+type FloatConfig = EmbedConfig & { _themeConfig?: ThemeConfig };
+
+function createNoOpHandle(researchId: string): FloatHandle {
+  return {
+    unmount: () => {},
+    update: () => {},
+    destroy: () => {},
+    open: () => {},
+    close: () => {},
+    toggle: () => {},
+    isOpen: false,
+    researchId,
+    type: "float",
+    iframe: null,
+    container: null,
+  };
+}
+
+export function createFloatBubble(config: FloatConfig): FloatHandle {
+  const { researchId, _themeConfig, theme, brand } = config;
+
+  // SSR safety: return no-op handle
+  if (!hasDom()) {
+    return createNoOpHandle(researchId);
+  }
+  const host = getHost(config.host);
+
+  injectStyles();
+  ensureGlobalListeners();
+
+  // Create bubble button
+  const bubble = document.createElement("button");
+  bubble.className = cn(
+    "perspective-float-bubble perspective-embed-root",
+    getThemeClass(config.theme)
+  );
+  bubble.innerHTML = MIC_ICON;
+  bubble.setAttribute("aria-label", "Open chat");
+  bubble.setAttribute("data-perspective", "float-bubble");
+
+  // Apply theme color if available
+  if (_themeConfig || brand) {
+    const isDark = resolveIsDark(theme);
+    const bg = isDark
+      ? (brand?.dark?.primary ?? _themeConfig?.darkPrimaryColor ?? "#a78bfa")
+      : (brand?.light?.primary ?? _themeConfig?.primaryColor ?? "#7c3aed");
+    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`;
+  }
+
+  document.body.appendChild(bubble);
+
+  let floatWindow: HTMLElement | null = null;
+  let iframe: HTMLIFrameElement | null = null;
+  let cleanup: (() => void) | null = null;
+  let unregisterIframe: (() => void) | null = null;
+  let isOpen = false;
+
+  // Mutable config reference for updates
+  let currentConfig = { ...config };
+
+  const openFloat = () => {
+    if (isOpen) return;
+    isOpen = true;
+
+    // Create float window
+    floatWindow = document.createElement("div");
+    floatWindow.className = cn(
+      "perspective-float-window perspective-embed-root",
+      getThemeClass(currentConfig.theme)
+    );
+
+    // Create close button
+    const closeBtn = document.createElement("button");
+    closeBtn.className = "perspective-close";
+    closeBtn.innerHTML = CLOSE_ICON;
+    closeBtn.setAttribute("aria-label", "Close chat");
+    closeBtn.addEventListener("click", closeFloat);
+
+    // Create loading indicator with theme and brand colors
+    const loading = createLoadingIndicator({
+      theme: currentConfig.theme,
+      brand: currentConfig.brand,
+    });
+    loading.style.borderRadius = "16px";
+
+    // Create iframe (hidden initially)
+    iframe = createIframe(
+      researchId,
+      "float",
+      host,
+      currentConfig.params,
+      currentConfig.brand,
+      currentConfig.theme
+    );
+    iframe.style.opacity = "0";
+    iframe.style.transition = "opacity 0.3s ease";
+
+    floatWindow.appendChild(closeBtn);
+    floatWindow.appendChild(loading);
+    floatWindow.appendChild(iframe);
+    document.body.appendChild(floatWindow);
+
+    // Set up message listener with loading state handling
+    cleanup = setupMessageListener(
+      researchId,
+      {
+        get onReady() {
+          return () => {
+            loading.style.opacity = "0";
+            iframe!.style.opacity = "1";
+            setTimeout(() => loading.remove(), 300);
+            currentConfig.onReady?.();
+          };
+        },
+        get onSubmit() {
+          return currentConfig.onSubmit;
+        },
+        get onNavigate() {
+          return currentConfig.onNavigate;
+        },
+        get onClose() {
+          return closeFloat;
+        },
+        get onError() {
+          return currentConfig.onError;
+        },
+      },
+      iframe,
+      host,
+      { skipResize: true }
+    );
+
+    // Register iframe for theme change notifications
+    if (iframe) {
+      unregisterIframe = registerIframe(iframe, host);
+    }
+
+    // Update bubble icon to close
+    bubble.innerHTML = CLOSE_ICON;
+    bubble.setAttribute("aria-label", "Close chat");
+  };
+
+  const closeFloat = () => {
+    if (!isOpen) return;
+    isOpen = false;
+
+    cleanup?.();
+    unregisterIframe?.();
+    floatWindow?.remove();
+    floatWindow = null;
+    iframe = null;
+    cleanup = null;
+    unregisterIframe = null;
+
+    // Restore bubble icon
+    bubble.innerHTML = MIC_ICON;
+    bubble.setAttribute("aria-label", "Open chat");
+
+    currentConfig.onClose?.();
+  };
+
+  // Toggle on bubble click
+  bubble.addEventListener("click", () => {
+    if (isOpen) {
+      closeFloat();
+    } else {
+      openFloat();
+    }
+  });
+
+  const unmount = () => {
+    closeFloat();
+    bubble.remove();
+  };
+
+  return {
+    unmount,
+    update: (options: Parameters<FloatHandle["update"]>[0]) => {
+      currentConfig = { ...currentConfig, ...options };
+    },
+    destroy: unmount,
+    open: openFloat,
+    close: closeFloat,
+    toggle: () => {
+      if (isOpen) {
+        closeFloat();
+      } else {
+        openFloat();
+      }
+    },
+    get isOpen() {
+      return isOpen;
+    },
+    researchId,
+    type: "float" as const,
+    get iframe() {
+      return iframe;
+    },
+    container: bubble,
+  };
+}
+
+/** @deprecated Use createFloatBubble instead */
+export const createChatBubble = createFloatBubble;

package/src/fullpage.test.ts

@@ -0,0 +1,224 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createFullpage } from "./fullpage";
+import * as config from "./config";
+
+describe("createFullpage", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("creates fullpage container", () => {
+    const handle = createFullpage({
+      researchId: "test-research-id",
+    });
+
+    expect(handle.researchId).toBe("test-research-id");
+    expect(handle.type).toBe("fullpage");
+    expect(handle.iframe).toBeInstanceOf(HTMLIFrameElement);
+    expect(document.querySelector(".perspective-fullpage")).toBeTruthy();
+
+    handle.unmount();
+  });
+
+  it("creates loading indicator", () => {
+    const handle = createFullpage({
+      researchId: "test-research-id",
+    });
+
+    const loading = document.querySelector(".perspective-loading");
+    expect(loading).toBeTruthy();
+
+    handle.unmount();
+  });
+
+  it("returns no-op handle when no DOM", () => {
+    vi.spyOn(config, "hasDom").mockReturnValue(false);
+
+    const handle = createFullpage({
+      researchId: "test-research-id",
+    });
+
+    expect(handle.iframe).toBeNull();
+    expect(handle.container).toBeNull();
+    expect(handle.unmount).toBeInstanceOf(Function);
+    expect(() => handle.unmount()).not.toThrow();
+  });
+
+  it("unmount removes fullpage container", () => {
+    const handle = createFullpage({
+      researchId: "test-research-id",
+    });
+
+    expect(document.querySelector(".perspective-fullpage")).toBeTruthy();
+
+    handle.unmount();
+
+    expect(document.querySelector(".perspective-fullpage")).toBeFalsy();
+  });
+
+  it("destroy is alias for unmount", () => {
+    const handle = createFullpage({
+      researchId: "test-research-id",
+    });
+
+    expect(document.querySelector(".perspective-fullpage")).toBeTruthy();
+
+    handle.destroy();
+
+    expect(document.querySelector(".perspective-fullpage")).toBeFalsy();
+  });
+
+  it("calls onClose on unmount", () => {
+    const onClose = vi.fn();
+    const handle = createFullpage({
+      researchId: "test-research-id",
+      onClose,
+    });
+
+    handle.unmount();
+
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("applies theme class", () => {
+    const handle = createFullpage({
+      researchId: "test-research-id",
+      theme: "dark",
+    });
+
+    const container = document.querySelector(".perspective-fullpage");
+    expect(container?.classList.contains("perspective-dark-theme")).toBe(true);
+
+    handle.unmount();
+  });
+
+  it("uses custom host", () => {
+    const handle = createFullpage({
+      researchId: "test-research-id",
+      host: "https://custom.example.com",
+    });
+
+    const iframe = handle.iframe as HTMLIFrameElement;
+    expect(iframe.src).toContain("https://custom.example.com");
+
+    handle.unmount();
+  });
+
+  it("passes params to iframe", () => {
+    const handle = createFullpage({
+      researchId: "test-research-id",
+      params: { source: "test", campaign: "demo" },
+    });
+
+    const iframe = handle.iframe as HTMLIFrameElement;
+    const url = new URL(iframe.src);
+    expect(url.searchParams.get("source")).toBe("test");
+    expect(url.searchParams.get("campaign")).toBe("demo");
+
+    handle.unmount();
+  });
+
+  it("update modifies config", () => {
+    const onSubmit1 = vi.fn();
+    const onSubmit2 = vi.fn();
+
+    const handle = createFullpage({
+      researchId: "test-research-id",
+      onSubmit: onSubmit1,
+    });
+
+    expect(() => handle.update({ onSubmit: onSubmit2 })).not.toThrow();
+
+    handle.unmount();
+  });
+
+  describe("update() behavior", () => {
+    const host = "https://getperspective.ai";
+    const researchId = "test-research-id";
+
+    const sendMessage = (
+      iframe: HTMLIFrameElement,
+      type: string,
+      extra?: Record<string, unknown>
+    ) => {
+      window.dispatchEvent(
+        new MessageEvent("message", {
+          data: { type, researchId, ...extra },
+          origin: host,
+          source: iframe.contentWindow,
+        })
+      );
+    };
+
+    it("update changes which callback is invoked", () => {
+      const onSubmit1 = vi.fn();
+      const onSubmit2 = vi.fn();
+
+      const handle = createFullpage({
+        researchId,
+        host,
+        onSubmit: onSubmit1,
+      });
+
+      handle.update({ onSubmit: onSubmit2 });
+
+      sendMessage(handle.iframe!, "perspective:submit");
+
+      expect(onSubmit2).toHaveBeenCalledTimes(1);
+      expect(onSubmit1).not.toHaveBeenCalled();
+
+      handle.unmount();
+    });
+
+    it("sequential updates only use latest callback", () => {
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      const fn3 = vi.fn();
+
+      const handle = createFullpage({
+        researchId,
+        host,
+        onSubmit: fn1,
+      });
+
+      handle.update({ onSubmit: fn2 });
+      handle.update({ onSubmit: fn3 });
+
+      sendMessage(handle.iframe!, "perspective:submit");
+
+      expect(fn3).toHaveBeenCalledTimes(1);
+      expect(fn2).not.toHaveBeenCalled();
+      expect(fn1).not.toHaveBeenCalled();
+
+      handle.unmount();
+    });
+
+    it("destroy prevents further callback invocations", () => {
+      const onSubmit = vi.fn();
+      const onClose = vi.fn();
+
+      const handle = createFullpage({
+        researchId,
+        host,
+        onSubmit,
+        onClose,
+      });
+
+      const iframe = handle.iframe!;
+
+      handle.unmount();
+      expect(onClose).toHaveBeenCalledTimes(1);
+
+      sendMessage(iframe, "perspective:submit");
+      sendMessage(iframe, "perspective:close");
+
+      expect(onSubmit).not.toHaveBeenCalled();
+      expect(onClose).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/fullpage.ts

@@ -0,0 +1,126 @@
+/**
+ * Fullpage embed - takes over entire viewport
+ * SSR-safe - returns no-op handle on server
+ */
+
+import type { EmbedConfig, EmbedHandle } from "./types";
+import { hasDom, getHost } from "./config";
+import {
+  createIframe,
+  setupMessageListener,
+  registerIframe,
+  ensureGlobalListeners,
+} from "./iframe";
+import { createLoadingIndicator } from "./loading";
+import { injectStyles } from "./styles";
+import { cn, getThemeClass } from "./utils";
+
+function createNoOpHandle(researchId: string): EmbedHandle {
+  return {
+    unmount: () => {},
+    update: () => {},
+    destroy: () => {},
+    researchId,
+    type: "fullpage" as const,
+    iframe: null,
+    container: null,
+  };
+}
+
+export function createFullpage(config: EmbedConfig): EmbedHandle {
+  const { researchId } = config;
+
+  // SSR safety: return no-op handle
+  if (!hasDom()) {
+    return createNoOpHandle(researchId);
+  }
+  const host = getHost(config.host);
+
+  injectStyles();
+  ensureGlobalListeners();
+
+  // Create fullpage container
+  const container = document.createElement("div");
+  container.className = cn(
+    "perspective-embed-root perspective-fullpage",
+    getThemeClass(config.theme)
+  );
+
+  // Create loading indicator with theme and brand colors
+  const loading = createLoadingIndicator({
+    theme: config.theme,
+    brand: config.brand,
+  });
+  container.appendChild(loading);
+
+  // Create iframe (hidden initially)
+  const iframe = createIframe(
+    researchId,
+    "fullpage",
+    host,
+    config.params,
+    config.brand,
+    config.theme
+  );
+  iframe.style.opacity = "0";
+  iframe.style.transition = "opacity 0.3s ease";
+
+  container.appendChild(iframe);
+  document.body.appendChild(container);
+
+  // Mutable config reference for updates
+  let currentConfig = { ...config };
+  let messageCleanup: (() => void) | null = null;
+
+  // Register iframe for theme change notifications
+  const unregisterIframe = registerIframe(iframe, host);
+
+  const unmount = () => {
+    messageCleanup?.();
+    unregisterIframe();
+    container.remove();
+    currentConfig.onClose?.();
+  };
+
+  // Set up message listener
+  messageCleanup = setupMessageListener(
+    researchId,
+    {
+      get onReady() {
+        return () => {
+          loading.style.opacity = "0";
+          iframe.style.opacity = "1";
+          setTimeout(() => loading.remove(), 300);
+          currentConfig.onReady?.();
+        };
+      },
+      get onSubmit() {
+        return currentConfig.onSubmit;
+      },
+      get onNavigate() {
+        return currentConfig.onNavigate;
+      },
+      get onClose() {
+        return unmount;
+      },
+      get onError() {
+        return currentConfig.onError;
+      },
+    },
+    iframe,
+    host,
+    { skipResize: true }
+  );
+
+  return {
+    unmount,
+    update: (options) => {
+      currentConfig = { ...currentConfig, ...options };
+    },
+    destroy: unmount,
+    researchId,
+    type: "fullpage" as const,
+    iframe,
+    container,
+  };
+}