@perspective-ai/sdk 1.0.1 → 1.1.2

package/src/constants.ts

@@ -9,7 +9,7 @@
 // ============================================================================
 
 /** SDK version for handshake protocol */
-export const SDK_VERSION = "1.0.0";
+export const SDK_VERSION = "1.1.2";
 
 /** Feature flags as bitset for version negotiation */
 export const FEATURES = {
@@ -60,36 +60,12 @@ export const BRAND_KEYS = {
 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)
+// Reserved Parameters (cannot be overridden via custom params or parent URL)
 // ============================================================================
 
 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,
+  ...Object.values(PARAM_KEYS),
+  ...Object.values(BRAND_KEYS),
 ]);
 
 // ============================================================================
@@ -108,6 +84,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];
@@ -191,4 +169,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.test.ts

@@ -62,6 +62,121 @@ describe("createIframe", () => {
     expect(src.searchParams.get(PARAM_KEYS.theme)).toBe("dark");
   });
 
+  it("forwards parent page search params to iframe", () => {
+    // Simulate parent page URL with search params
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: { ...originalLocation, search: "?ref=pricing-enterprise&foo=bar" },
+      writable: true,
+      configurable: true,
+    });
+
+    const iframe = createIframe(
+      "test-research-id",
+      "widget",
+      "https://getperspective.ai"
+    );
+
+    const src = new URL(iframe.src);
+    expect(src.searchParams.get("ref")).toBe("pricing-enterprise");
+    expect(src.searchParams.get("foo")).toBe("bar");
+
+    Object.defineProperty(window, "location", {
+      value: originalLocation,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  it("does not forward reserved params from parent URL", () => {
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: {
+        ...originalLocation,
+        search: "?embed=false&theme=dark&ref=test",
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const iframe = createIframe(
+      "test-research-id",
+      "widget",
+      "https://getperspective.ai"
+    );
+
+    const src = new URL(iframe.src);
+    // Reserved params should be set by SDK, not from parent URL
+    expect(src.searchParams.get(PARAM_KEYS.embed)).toBe("true");
+    // Non-reserved params should be forwarded
+    expect(src.searchParams.get("ref")).toBe("test");
+
+    Object.defineProperty(window, "location", {
+      value: originalLocation,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  it("custom params override parent URL params", () => {
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: { ...originalLocation, search: "?ref=from-url&source=parent" },
+      writable: true,
+      configurable: true,
+    });
+
+    const iframe = createIframe(
+      "test-research-id",
+      "widget",
+      "https://getperspective.ai",
+      { ref: "from-custom", extra: "value" }
+    );
+
+    const src = new URL(iframe.src);
+    // Custom params should override parent URL params
+    expect(src.searchParams.get("ref")).toBe("from-custom");
+    // Parent-only params should still be forwarded
+    expect(src.searchParams.get("source")).toBe("parent");
+    // Custom-only params should be present
+    expect(src.searchParams.get("extra")).toBe("value");
+
+    Object.defineProperty(window, "location", {
+      value: originalLocation,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  it("forwards UTM params from parent URL", () => {
+    const originalLocation = window.location;
+    Object.defineProperty(window, "location", {
+      value: {
+        ...originalLocation,
+        search: "?utm_source=google&utm_campaign=summer&ref=pricing",
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    const iframe = createIframe(
+      "test-research-id",
+      "widget",
+      "https://getperspective.ai"
+    );
+
+    const src = new URL(iframe.src);
+    expect(src.searchParams.get("utm_source")).toBe("google");
+    expect(src.searchParams.get("utm_campaign")).toBe("summer");
+    expect(src.searchParams.get("ref")).toBe("pricing");
+
+    Object.defineProperty(window, "location", {
+      value: originalLocation,
+      writable: true,
+      configurable: true,
+    });
+  });
+
   it("includes brand colors", () => {
     const iframe = createIframe(
       "test-research-id",

package/src/iframe.ts

@@ -11,7 +11,6 @@ import type {
 } from "./types";
 import { hasDom } from "./config";
 import {
-  UTM_PARAMS,
   RESERVED_PARAMS,
   PARAM_KEYS,
   BRAND_KEYS,
@@ -63,16 +62,15 @@ function getOrCreateAnonId(): string {
   }
 }
 
-/** Collect UTM params from current page URL */
-function getUtmParams(): Record<string, string> {
+/** Collect all search params from the parent page URL (excluding reserved SDK params) */
+function getParentSearchParams(): Record<string, string> {
   if (!hasDom()) return {};
 
   const params: Record<string, string> = {};
   const searchParams = new URLSearchParams(window.location.search);
 
-  for (const key of UTM_PARAMS) {
-    const value = searchParams.get(key);
-    if (value) {
+  for (const [key, value] of searchParams.entries()) {
+    if (!RESERVED_PARAMS.has(key)) {
       params[key] = value;
     }
   }
@@ -111,9 +109,10 @@ function buildIframeUrl(
     url.searchParams.set(PARAM_KEYS.theme, themeOverride || THEME_VALUES.light);
   }
 
-  // Auto-forward UTM params from parent
-  const utmParams = getUtmParams();
-  for (const [key, value] of Object.entries(utmParams)) {
+  // Auto-forward all parent page search params (e.g. ?ref=pricing-enterprise)
+  // These are added first so that explicit customParams can override them
+  const parentParams = getParentSearchParams();
+  for (const [key, value] of Object.entries(parentParams)) {
     url.searchParams.set(key, value);
   }
 

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