@perspective-ai/sdk 1.1.0 → 1.1.2

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 */