@perspective-ai/sdk 1.1.0 → 1.1.3

package/src/browser.ts

@@ -24,6 +24,13 @@ import type {
   ThemeConfig,
 } from "./types";
 import { DATA_ATTRS, THEME_VALUES } from "./constants";
+import {
+  parseTriggerAttr,
+  parseShowOnceAttr,
+  setupTrigger,
+  shouldShow,
+  markShown,
+} from "./triggers";
 import { createWidget } from "./widget";
 import { openPopup } from "./popup";
 import { openSlider } from "./slider";
@@ -35,6 +42,9 @@ import { resolveIsDark } from "./utils";
 // Track all active instances
 const instances: Map<string, EmbedHandle | FloatHandle> = new Map();
 
+// Track auto-open trigger cleanups (keyed by researchId)
+const triggerCleanups: Map<string, () => void> = new Map();
+
 // Theme config cache
 const configCache: Map<string, ThemeConfig> = new Map();
 
@@ -317,8 +327,16 @@ function destroy(researchId: string): void {
 function destroyAll(): void {
   instances.forEach((instance) => instance.unmount());
   instances.clear();
+  triggerCleanups.forEach((cleanup) => cleanup());
+  triggerCleanups.clear();
   styledButtons.clear();
   teardownButtonThemeListener();
+  // Reset initialized flags so autoInit can re-process elements cleanly
+  if (hasDom()) {
+    document
+      .querySelectorAll<HTMLElement>("[data-perspective-initialized]")
+      .forEach((el) => el.removeAttribute("data-perspective-initialized"));
+  }
 }
 
 /**
@@ -361,9 +379,36 @@ function autoInit(): void {
       el.setAttribute("data-perspective-initialized", "true");
 
       const researchId = el.getAttribute(DATA_ATTRS.popup);
-      if (researchId) {
-        const params = parseParamsAttr(el);
-        const brandConfig = extractBrandConfig(el);
+      if (!researchId) return;
+
+      const params = parseParamsAttr(el);
+      const brandConfig = extractBrandConfig(el);
+      const autoOpenAttr = el.getAttribute(DATA_ATTRS.autoOpen);
+
+      if (autoOpenAttr) {
+        // Auto-open mode: trigger-based, no button styling
+        try {
+          const trigger = parseTriggerAttr(autoOpenAttr);
+          const showOnce = parseShowOnceAttr(
+            el.getAttribute(DATA_ATTRS.showOnce)
+          );
+
+          if (shouldShow(researchId, showOnce)) {
+            // Clean up any existing trigger for this researchId
+            triggerCleanups.get(researchId)?.();
+
+            const cleanup = setupTrigger(trigger, () => {
+              triggerCleanups.delete(researchId);
+              markShown(researchId, showOnce);
+              init({ researchId, type: "popup", params, ...brandConfig });
+            });
+            triggerCleanups.set(researchId, cleanup);
+          }
+        } catch (e) {
+          console.warn("[Perspective]", (e as Error).message);
+        }
+      } else {
+        // Click-to-open mode: styled button
         styleButton(el, DEFAULT_THEME, brandConfig);
         el.addEventListener("click", (e) => {
           e.preventDefault();

package/src/constants.ts

@@ -8,8 +8,9 @@
 // SDK Version & Features
 // ============================================================================
 
-/** SDK version for handshake protocol */
-export const SDK_VERSION = "1.1.0";
+/** SDK version for handshake protocol — replaced at build time by tsup define */
+declare const PKG_VERSION: string;
+export const SDK_VERSION = PKG_VERSION;
 
 /** Feature flags as bitset for version negotiation */
 export const FEATURES = {
@@ -84,6 +85,8 @@ export const DATA_ATTRS = {
   brandDark: "data-perspective-brand-dark",
   theme: "data-perspective-theme",
   noStyle: "data-perspective-no-style",
+  autoOpen: "data-perspective-auto-open",
+  showOnce: "data-perspective-show-once",
 } as const;
 
 export type DataAttr = (typeof DATA_ATTRS)[keyof typeof DATA_ATTRS];
@@ -167,4 +170,5 @@ export type ModeValue = (typeof MODE_VALUES)[keyof typeof MODE_VALUES];
 
 export const STORAGE_KEYS = {
   anonId: "perspective-anon-id",
+  triggerShown: "perspective-trigger-shown",
 } as const;

package/src/iframe.ts

@@ -27,6 +27,14 @@ import { normalizeHex } from "./utils";
 /** Validate redirect URL - allow https, http localhost, and relative URLs */
 function isAllowedRedirectUrl(url: string): boolean {
   if (!url || typeof url !== "string") return false;
+  // Relative URLs (path, query, hash) are always safe — same origin by definition
+  // Exclude protocol-relative URLs (// prefix) which resolve to an external origin
+  if (
+    (url.startsWith("/") && !url.startsWith("//")) ||
+    url.startsWith("?") ||
+    url.startsWith("#")
+  )
+    return true;
   try {
     const parsed = new URL(url, window.location.origin);
     const protocol = parsed.protocol.toLowerCase();

package/src/index.ts

@@ -29,6 +29,15 @@ export { openSlider } from "./slider";
 export { createFloatBubble, createChatBubble } from "./float";
 export { createFullpage } from "./fullpage";
 
+// Auto-open triggers
+export {
+  setupTrigger,
+  parseTriggerAttr,
+  parseShowOnceAttr,
+  shouldShow,
+  markShown,
+} from "./triggers";
+
 // Configuration
 export { configure, getConfig } from "./config";
 
@@ -44,6 +53,10 @@ export type {
   EmbedType,
   ThemeConfig,
   SDKConfig,
+  TriggerType,
+  TriggerConfig,
+  ShowOnce,
+  AutoOpenConfig,
 } from "./types";
 
 // Re-export commonly used constants and types

package/src/triggers.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  parseTriggerAttr,
+  parseShowOnceAttr,
+  setupTrigger,
+  shouldShow,
+  markShown,
+} from "./triggers";
+
+describe("triggers", () => {
+  describe("parseTriggerAttr", () => {
+    it("parses timeout with delay", () => {
+      expect(parseTriggerAttr("timeout:5000")).toEqual({
+        type: "timeout",
+        delay: 5000,
+      });
+    });
+
+    it("parses timeout with zero delay", () => {
+      expect(parseTriggerAttr("timeout:0")).toEqual({
+        type: "timeout",
+        delay: 0,
+      });
+    });
+
+    it("parses bare timeout as 5000ms default", () => {
+      expect(parseTriggerAttr("timeout")).toEqual({
+        type: "timeout",
+        delay: 5000,
+      });
+    });
+
+    it("parses exit-intent", () => {
+      expect(parseTriggerAttr("exit-intent")).toEqual({
+        type: "exit-intent",
+      });
+    });
+
+    it("trims whitespace", () => {
+      expect(parseTriggerAttr("  timeout:3000  ")).toEqual({
+        type: "timeout",
+        delay: 3000,
+      });
+    });
+
+    it("throws on invalid timeout delay", () => {
+      expect(() => parseTriggerAttr("timeout:abc")).toThrow(
+        "Invalid timeout delay"
+      );
+    });
+
+    it("throws on negative timeout delay", () => {
+      expect(() => parseTriggerAttr("timeout:-1")).toThrow(
+        "Invalid timeout delay"
+      );
+    });
+
+    it("throws on unknown trigger type", () => {
+      expect(() => parseTriggerAttr("scroll:50")).toThrow(
+        "Unknown trigger type"
+      );
+    });
+  });
+
+  describe("setupTrigger", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("calls callback after timeout delay", () => {
+      const callback = vi.fn();
+      setupTrigger({ type: "timeout", delay: 3000 }, callback);
+
+      expect(callback).not.toHaveBeenCalled();
+      vi.advanceTimersByTime(2999);
+      expect(callback).not.toHaveBeenCalled();
+      vi.advanceTimersByTime(1);
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns cleanup that clears timeout", () => {
+      const callback = vi.fn();
+      const cleanup = setupTrigger({ type: "timeout", delay: 3000 }, callback);
+
+      cleanup();
+      vi.advanceTimersByTime(5000);
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it("sets up exit-intent on mouseleave", () => {
+      const callback = vi.fn();
+      const addSpy = vi.spyOn(document, "addEventListener");
+
+      setupTrigger({ type: "exit-intent" }, callback);
+
+      expect(addSpy).toHaveBeenCalledWith("mouseleave", expect.any(Function));
+      addSpy.mockRestore();
+    });
+
+    it("fires exit-intent callback when clientY <= 0", () => {
+      const callback = vi.fn();
+      setupTrigger({ type: "exit-intent" }, callback);
+
+      // Simulate mouse leaving the document upward
+      const event = new MouseEvent("mouseleave", { clientY: -1 });
+      document.dispatchEvent(event);
+
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not fire exit-intent when clientY > 0", () => {
+      const callback = vi.fn();
+      setupTrigger({ type: "exit-intent" }, callback);
+
+      const event = new MouseEvent("mouseleave", { clientY: 100 });
+      document.dispatchEvent(event);
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it("removes exit-intent listener after firing", () => {
+      const callback = vi.fn();
+      setupTrigger({ type: "exit-intent" }, callback);
+
+      const event1 = new MouseEvent("mouseleave", { clientY: -1 });
+      document.dispatchEvent(event1);
+      expect(callback).toHaveBeenCalledTimes(1);
+
+      // Second event should not fire
+      const event2 = new MouseEvent("mouseleave", { clientY: -1 });
+      document.dispatchEvent(event2);
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it("returns cleanup that removes exit-intent listener", () => {
+      const callback = vi.fn();
+      const removeSpy = vi.spyOn(document, "removeEventListener");
+
+      const cleanup = setupTrigger({ type: "exit-intent" }, callback);
+      cleanup();
+
+      expect(removeSpy).toHaveBeenCalledWith(
+        "mouseleave",
+        expect.any(Function)
+      );
+
+      // Event should not fire after cleanup
+      const event = new MouseEvent("mouseleave", { clientY: -1 });
+      document.dispatchEvent(event);
+      expect(callback).not.toHaveBeenCalled();
+
+      removeSpy.mockRestore();
+    });
+  });
+
+  describe("parseShowOnceAttr", () => {
+    it('returns "session" for null', () => {
+      expect(parseShowOnceAttr(null)).toBe("session");
+    });
+
+    it('returns "session" for empty string', () => {
+      expect(parseShowOnceAttr("")).toBe("session");
+    });
+
+    it('returns "session" for "session"', () => {
+      expect(parseShowOnceAttr("session")).toBe("session");
+    });
+
+    it('returns "visitor" for "visitor"', () => {
+      expect(parseShowOnceAttr("visitor")).toBe("visitor");
+    });
+
+    it('returns false for "false"', () => {
+      expect(parseShowOnceAttr("false")).toBe(false);
+    });
+
+    it('defaults unknown values to "session"', () => {
+      expect(parseShowOnceAttr("always")).toBe("session");
+      expect(parseShowOnceAttr("never")).toBe("session");
+    });
+
+    it("trims whitespace", () => {
+      expect(parseShowOnceAttr("  visitor  ")).toBe("visitor");
+    });
+  });
+
+  describe("shouldShow / markShown", () => {
+    beforeEach(() => {
+      sessionStorage.clear();
+      localStorage.clear();
+    });
+
+    it("returns true when no prior shown (session)", () => {
+      expect(shouldShow("test-id", "session")).toBe(true);
+    });
+
+    it("returns true when no prior shown (visitor)", () => {
+      expect(shouldShow("test-id", "visitor")).toBe(true);
+    });
+
+    it("returns true when showOnce is false", () => {
+      expect(shouldShow("test-id", false)).toBe(true);
+    });
+
+    it("returns false after markShown (session)", () => {
+      markShown("test-id", "session");
+      expect(shouldShow("test-id", "session")).toBe(false);
+    });
+
+    it("returns false after markShown (visitor)", () => {
+      markShown("test-id", "visitor");
+      expect(shouldShow("test-id", "visitor")).toBe(false);
+    });
+
+    it("always returns true when showOnce is false, even after markShown", () => {
+      markShown("test-id", false);
+      expect(shouldShow("test-id", false)).toBe(true);
+    });
+
+    it("uses sessionStorage for session mode", () => {
+      markShown("test-id", "session");
+      expect(sessionStorage.getItem("perspective-trigger-shown:test-id")).toBe(
+        "1"
+      );
+      expect(
+        localStorage.getItem("perspective-trigger-shown:test-id")
+      ).toBeNull();
+    });
+
+    it("uses localStorage for visitor mode", () => {
+      markShown("test-id", "visitor");
+      expect(localStorage.getItem("perspective-trigger-shown:test-id")).toBe(
+        "1"
+      );
+      expect(
+        sessionStorage.getItem("perspective-trigger-shown:test-id")
+      ).toBeNull();
+    });
+
+    it("deduplicates per researchId", () => {
+      markShown("id-1", "session");
+      expect(shouldShow("id-1", "session")).toBe(false);
+      expect(shouldShow("id-2", "session")).toBe(true);
+    });
+
+    it("shouldShow returns true when storage throws", () => {
+      const spy = vi
+        .spyOn(Storage.prototype, "getItem")
+        .mockImplementation(() => {
+          throw new Error("Storage disabled");
+        });
+      expect(shouldShow("test-id", "session")).toBe(true);
+      expect(shouldShow("test-id", "visitor")).toBe(true);
+      spy.mockRestore();
+    });
+
+    it("markShown does not throw when storage throws", () => {
+      const spy = vi
+        .spyOn(Storage.prototype, "setItem")
+        .mockImplementation(() => {
+          throw new Error("Storage disabled");
+        });
+      expect(() => markShown("test-id", "session")).not.toThrow();
+      expect(() => markShown("test-id", "visitor")).not.toThrow();
+      spy.mockRestore();
+    });
+  });
+});

package/src/triggers.ts

@@ -0,0 +1,127 @@
+/**
+ * Auto-open trigger system for popup embeds.
+ *
+ * Supports:
+ * - Timeout: Open after a delay (ms)
+ * - Exit intent: Open when user moves cursor above viewport
+ *
+ * Show-once dedup:
+ * - "session" -> sessionStorage
+ * - "visitor" -> localStorage
+ * - false -> always show
+ */
+
+import { STORAGE_KEYS } from "./constants";
+import type { TriggerConfig, ShowOnce } from "./types";
+
+/**
+ * Parse a trigger attribute value into a TriggerConfig.
+ *
+ * Formats:
+ * - "timeout:5000" -> { type: "timeout", delay: 5000 }
+ * - "exit-intent"  -> { type: "exit-intent" }
+ */
+export function parseTriggerAttr(value: string): TriggerConfig {
+  const trimmed = value.trim();
+
+  if (trimmed.startsWith("timeout:")) {
+    const delay = parseInt(trimmed.slice("timeout:".length), 10);
+    if (isNaN(delay) || delay < 0) {
+      throw new Error(`Invalid timeout delay: "${value}"`);
+    }
+    return { type: "timeout", delay };
+  }
+
+  if (trimmed === "timeout") {
+    return { type: "timeout", delay: 5000 };
+  }
+
+  if (trimmed === "exit-intent") {
+    return { type: "exit-intent" };
+  }
+
+  throw new Error(
+    `Unknown trigger type: "${value}". Expected "timeout:<ms>" or "exit-intent".`
+  );
+}
+
+/**
+ * Set up a trigger that calls `callback` when fired.
+ * Returns a cleanup function to teardown the trigger.
+ */
+export function setupTrigger(
+  config: TriggerConfig,
+  callback: () => void
+): () => void {
+  if (config.type === "timeout") {
+    const timer = setTimeout(callback, config.delay);
+    return () => clearTimeout(timer);
+  }
+
+  if (config.type === "exit-intent") {
+    const handler = (e: MouseEvent) => {
+      if (e.clientY <= 0) {
+        callback();
+        document.removeEventListener("mouseleave", handler);
+      }
+    };
+    document.addEventListener("mouseleave", handler);
+    return () => document.removeEventListener("mouseleave", handler);
+  }
+
+  // Exhaustive check
+  const _exhaustive: never = config;
+  throw new Error(
+    `Unknown trigger type: ${(_exhaustive as TriggerConfig).type}`
+  );
+}
+
+function storageKey(researchId: string): string {
+  return `${STORAGE_KEYS.triggerShown}:${researchId}`;
+}
+
+/**
+ * Parse a show-once attribute value into a ShowOnce.
+ *
+ * Formats:
+ * - "session"  -> "session"
+ * - "visitor"  -> "visitor"
+ * - "false"    -> false
+ * - anything else -> defaults to "session"
+ */
+export function parseShowOnceAttr(value: string | null): ShowOnce {
+  if (!value) return "session";
+  const trimmed = value.trim();
+  if (trimmed === "visitor") return "visitor";
+  if (trimmed === "false") return false;
+  return "session";
+}
+
+/**
+ * Check if the popup should be shown based on show-once dedup.
+ */
+export function shouldShow(researchId: string, showOnce: ShowOnce): boolean {
+  if (showOnce === false) return true;
+
+  try {
+    const storage = showOnce === "visitor" ? localStorage : sessionStorage;
+    return storage.getItem(storageKey(researchId)) === null;
+  } catch {
+    // Storage unavailable (private browsing, etc.) — show anyway
+    return true;
+  }
+}
+
+/**
+ * Mark the popup as shown for dedup purposes.
+ */
+export function markShown(researchId: string, showOnce: ShowOnce): void {
+  if (showOnce === false) return;
+
+  try {
+    const storage = showOnce === "visitor" ? localStorage : sessionStorage;
+    storage.setItem(storageKey(researchId), "1");
+  } catch {
+    // Storage unavailable — ignore
+  }
+}

package/src/types.ts

@@ -23,6 +23,23 @@ export type EmbedType =
   | "fullpage"
   | "chat";
 
+// ============================================================================
+// Auto-open Trigger Types
+// ============================================================================
+
+export type TriggerConfig =
+  | { type: "timeout"; delay: number }
+  | { type: "exit-intent" };
+
+export type TriggerType = TriggerConfig["type"];
+
+export type ShowOnce = "session" | "visitor" | false;
+
+export interface AutoOpenConfig {
+  trigger: TriggerConfig;
+  showOnce?: ShowOnce; // default: "session"
+}
+
 /** Brand colors that can be passed via embed code */
 export interface BrandColors {
   /** Primary accent color (buttons, links, focus states) */
@@ -51,6 +68,8 @@ export interface EmbedConfig {
   theme?: ThemeValue;
   /** Override the default host (defaults to https://getperspective.ai) */
   host?: string;
+  /** Auto-open trigger configuration (popup only) */
+  autoOpen?: AutoOpenConfig;
   /** Callback when embed is ready */
   onReady?: () => void;
   /** Callback when interview is submitted/completed */