@perspective-ai/sdk 1.0.0-alpha.2

package/src/constants.ts

@@ -0,0 +1,214 @@
+/**
+ * Shared constants for Perspective Embed SDK
+ * This file is SSR-safe - no DOM access at import time
+ * Used by both SDK bundle and the main Perspective app
+ */
+
+// ============================================================================
+// SDK Version & Features
+// ============================================================================
+
+/** SDK version for handshake protocol */
+export const SDK_VERSION = "1.0.0";
+
+/** Feature flags as bitset for version negotiation */
+export const FEATURES = {
+  RESIZE: 1 << 0, // 0b0001
+  THEME_SYNC: 1 << 1, // 0b0010
+  ANON_ID: 1 << 2, // 0b0100
+  SCROLLBAR_STYLES: 1 << 3, // 0b1000
+} as const;
+
+/** Current SDK feature set */
+export const CURRENT_FEATURES =
+  FEATURES.RESIZE |
+  FEATURES.THEME_SYNC |
+  FEATURES.ANON_ID |
+  FEATURES.SCROLLBAR_STYLES;
+
+// ============================================================================
+// URL Parameter Keys
+// ============================================================================
+
+export const PARAM_KEYS = {
+  // User identification
+  email: "email",
+  name: "name",
+
+  // Navigation
+  returnUrl: "returnUrl",
+
+  // Interview behavior
+  voice: "voice",
+  scroll: "scroll",
+  hideProgress: "hideProgress",
+  hideGreeting: "hideGreeting",
+  hideBranding: "hideBranding",
+
+  // Interview mode & auth
+  mode: "mode",
+  invite: "invite",
+
+  // System (internal)
+  embed: "embed",
+  embedType: "embed_type",
+  theme: "theme",
+} as const;
+
+export type ParamKey = (typeof PARAM_KEYS)[keyof typeof PARAM_KEYS];
+
+// ============================================================================
+// Brand Color Keys
+// ============================================================================
+
+export const BRAND_KEYS = {
+  // Light mode
+  primary: "brand.primary",
+  secondary: "brand.secondary",
+  bg: "brand.bg",
+  text: "brand.text",
+
+  // Dark mode
+  darkPrimary: "brand.dark.primary",
+  darkSecondary: "brand.dark.secondary",
+  darkBg: "brand.dark.bg",
+  darkText: "brand.dark.text",
+} as const;
+
+export type BrandKey = (typeof BRAND_KEYS)[keyof typeof BRAND_KEYS];
+
+// ============================================================================
+// UTM Parameters (auto-forwarded from parent URL)
+// ============================================================================
+
+export const UTM_PARAMS = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_term",
+  "utm_content",
+] as const;
+
+export type UtmParam = (typeof UTM_PARAMS)[number];
+
+// ============================================================================
+// Reserved Parameters (cannot be overridden via custom params)
+// ============================================================================
+
+export const RESERVED_PARAMS: Set<string> = new Set([
+  PARAM_KEYS.embed,
+  PARAM_KEYS.embedType,
+  PARAM_KEYS.theme,
+  BRAND_KEYS.primary,
+  BRAND_KEYS.secondary,
+  BRAND_KEYS.bg,
+  BRAND_KEYS.text,
+  BRAND_KEYS.darkPrimary,
+  BRAND_KEYS.darkSecondary,
+  BRAND_KEYS.darkBg,
+  BRAND_KEYS.darkText,
+  ...UTM_PARAMS,
+]);
+
+// ============================================================================
+// Data Attributes (HTML declarative initialization)
+// ============================================================================
+
+export const DATA_ATTRS = {
+  widget: "data-perspective-widget",
+  popup: "data-perspective-popup",
+  slider: "data-perspective-slider",
+  float: "data-perspective-float", // Primary name
+  chat: "data-perspective-chat", // Legacy alias
+  fullpage: "data-perspective-fullpage",
+  params: "data-perspective-params",
+  brand: "data-perspective-brand",
+  brandDark: "data-perspective-brand-dark",
+  theme: "data-perspective-theme",
+  noStyle: "data-perspective-no-style",
+} as const;
+
+export type DataAttr = (typeof DATA_ATTRS)[keyof typeof DATA_ATTRS];
+
+// ============================================================================
+// PostMessage Event Types
+// ============================================================================
+
+export const MESSAGE_TYPES = {
+  // SDK -> Iframe (initialization)
+  init: "perspective:init",
+
+  // Iframe -> SDK
+  ready: "perspective:ready",
+  resize: "perspective:resize",
+  submit: "perspective:submit",
+  close: "perspective:close",
+  error: "perspective:error",
+  redirect: "perspective:redirect",
+
+  // SDK -> Iframe (internal)
+  anonId: "perspective:anon-id",
+  injectStyles: "perspective:inject-styles",
+  themeChange: "perspective:theme-change",
+
+  // Iframe -> SDK (internal)
+  requestScrollbarStyles: "perspective:request-scrollbar-styles",
+} as const;
+
+export type MessageType = (typeof MESSAGE_TYPES)[keyof typeof MESSAGE_TYPES];
+
+// ============================================================================
+// Error Codes
+// ============================================================================
+
+export const ERROR_CODES = {
+  SDK_OUTDATED: "SDK_OUTDATED",
+  INVALID_RESEARCH: "INVALID_RESEARCH",
+  UNKNOWN: "UNKNOWN",
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+// ============================================================================
+// Param Values (for boolean-like string params)
+// ============================================================================
+
+export const PARAM_VALUES = {
+  disabled: "0",
+  enabled: "1",
+  true: "true",
+  false: "false",
+} as const;
+
+// ============================================================================
+// Theme Values
+// ============================================================================
+
+export const THEME_VALUES = {
+  dark: "dark",
+  light: "light",
+  system: "system",
+} as const;
+
+export type ThemeValue = (typeof THEME_VALUES)[keyof typeof THEME_VALUES];
+
+// ============================================================================
+// Interview Mode Values (for mode param)
+// ============================================================================
+
+export const MODE_VALUES = {
+  preview: "preview",
+  restart: "restart",
+  normal: "normal",
+  simulated: "simulated",
+} as const;
+
+export type ModeValue = (typeof MODE_VALUES)[keyof typeof MODE_VALUES];
+
+// ============================================================================
+// localStorage Keys
+// ============================================================================
+
+export const STORAGE_KEYS = {
+  anonId: "perspective-anon-id",
+} as const;

package/src/float.test.ts

@@ -0,0 +1,332 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { createFloatBubble, createChatBubble } from "./float";
+import * as config from "./config";
+
+describe("createFloatBubble", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("creates float bubble", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    expect(handle.researchId).toBe("test-research-id");
+    expect(handle.type).toBe("float");
+    expect(handle.isOpen).toBe(false);
+    expect(document.querySelector(".perspective-float-bubble")).toBeTruthy();
+
+    handle.unmount();
+  });
+
+  it("returns no-op handle when no DOM", () => {
+    vi.spyOn(config, "hasDom").mockReturnValue(false);
+
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    expect(handle.iframe).toBeNull();
+    expect(handle.container).toBeNull();
+    expect(handle.isOpen).toBe(false);
+    expect(handle.unmount).toBeInstanceOf(Function);
+    expect(() => handle.unmount()).not.toThrow();
+    expect(() => handle.open()).not.toThrow();
+    expect(() => handle.close()).not.toThrow();
+    expect(() => handle.toggle()).not.toThrow();
+  });
+
+  it("open() opens float window", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    expect(handle.isOpen).toBe(false);
+    expect(document.querySelector(".perspective-float-window")).toBeFalsy();
+
+    handle.open();
+
+    expect(handle.isOpen).toBe(true);
+    expect(document.querySelector(".perspective-float-window")).toBeTruthy();
+
+    handle.unmount();
+  });
+
+  it("close() closes float window", () => {
+    const onClose = vi.fn();
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+      onClose,
+    });
+
+    handle.open();
+    expect(handle.isOpen).toBe(true);
+    expect(document.querySelector(".perspective-float-window")).toBeTruthy();
+
+    handle.close();
+
+    expect(handle.isOpen).toBe(false);
+    expect(document.querySelector(".perspective-float-window")).toBeFalsy();
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("toggle() toggles float window", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    expect(handle.isOpen).toBe(false);
+
+    handle.toggle();
+    expect(handle.isOpen).toBe(true);
+    expect(document.querySelector(".perspective-float-window")).toBeTruthy();
+
+    handle.toggle();
+    expect(handle.isOpen).toBe(false);
+    expect(document.querySelector(".perspective-float-window")).toBeFalsy();
+
+    handle.unmount();
+  });
+
+  it("clicking bubble toggles float window", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    const bubble = document.querySelector(
+      ".perspective-float-bubble"
+    ) as HTMLButtonElement;
+    expect(bubble).toBeTruthy();
+
+    bubble.click();
+    expect(handle.isOpen).toBe(true);
+    expect(document.querySelector(".perspective-float-window")).toBeTruthy();
+
+    bubble.click();
+    expect(handle.isOpen).toBe(false);
+    expect(document.querySelector(".perspective-float-window")).toBeFalsy();
+
+    handle.unmount();
+  });
+
+  it("close button in float window closes it", () => {
+    const onClose = vi.fn();
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+      onClose,
+    });
+
+    handle.open();
+
+    const closeBtn = document.querySelector(
+      ".perspective-float-window .perspective-close"
+    ) as HTMLButtonElement;
+    expect(closeBtn).toBeTruthy();
+
+    closeBtn.click();
+
+    expect(handle.isOpen).toBe(false);
+    expect(document.querySelector(".perspective-float-window")).toBeFalsy();
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("unmount removes bubble and window", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    handle.open();
+    expect(document.querySelector(".perspective-float-bubble")).toBeTruthy();
+    expect(document.querySelector(".perspective-float-window")).toBeTruthy();
+
+    handle.unmount();
+
+    expect(document.querySelector(".perspective-float-bubble")).toBeFalsy();
+    expect(document.querySelector(".perspective-float-window")).toBeFalsy();
+  });
+
+  it("destroy is alias for unmount", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    expect(document.querySelector(".perspective-float-bubble")).toBeTruthy();
+
+    handle.destroy();
+
+    expect(document.querySelector(".perspective-float-bubble")).toBeFalsy();
+  });
+
+  it("open when already open is no-op", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+    });
+
+    handle.open();
+    const window1 = document.querySelector(".perspective-float-window");
+
+    handle.open();
+    const window2 = document.querySelector(".perspective-float-window");
+
+    expect(window1).toBe(window2);
+
+    handle.unmount();
+  });
+
+  it("close when already closed is no-op", () => {
+    const onClose = vi.fn();
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+      onClose,
+    });
+
+    handle.close();
+    handle.close();
+    handle.close();
+
+    expect(onClose).not.toHaveBeenCalled();
+
+    handle.unmount();
+  });
+
+  it("uses custom host", () => {
+    const handle = createFloatBubble({
+      researchId: "test-research-id",
+      host: "https://custom.example.com",
+    });
+
+    handle.open();
+
+    const iframe = handle.iframe as HTMLIFrameElement;
+    expect(iframe.src).toContain("https://custom.example.com");
+
+    handle.unmount();
+  });
+
+  it("update modifies config", () => {
+    const onSubmit1 = vi.fn();
+    const onSubmit2 = vi.fn();
+
+    const handle = createFloatBubble({
+      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 = createFloatBubble({
+        researchId,
+        host,
+        onSubmit: onSubmit1,
+      });
+
+      handle.open();
+      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 = createFloatBubble({
+        researchId,
+        host,
+        onSubmit: fn1,
+      });
+
+      handle.open();
+      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("close prevents further callback invocations from that window", () => {
+      const onSubmit = vi.fn();
+      const onClose = vi.fn();
+
+      const handle = createFloatBubble({
+        researchId,
+        host,
+        onSubmit,
+        onClose,
+      });
+
+      handle.open();
+      const iframe = handle.iframe!;
+
+      handle.close();
+      expect(onClose).toHaveBeenCalledTimes(1);
+
+      sendMessage(iframe, "perspective:submit");
+
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+  });
+});
+
+describe("createChatBubble", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("is alias for createFloatBubble", () => {
+    expect(createChatBubble).toBe(createFloatBubble);
+  });
+
+  it("creates float bubble", () => {
+    const handle = createChatBubble({
+      researchId: "test-research-id",
+    });
+
+    expect(handle.type).toBe("float");
+    expect(document.querySelector(".perspective-float-bubble")).toBeTruthy();
+
+    handle.unmount();
+  });
+});