polymorph-sdk 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polymorph-sdk",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "sideEffects": false,
   "main": "src/index.ts",

package/src/IdentityForm.tsx

@@ -7,6 +7,8 @@ interface IdentityFormProps {
   collectPhone: FieldRequirement;
   primaryColor: string;
   onSubmit: (user: WidgetUser) => void;
+  enableTermsAndConditions?: boolean;
+  termsAndConditionsText?: string;
 }
 
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[a-zA-Z]{2,}$/;
@@ -17,10 +19,13 @@ export function IdentityForm({
   collectPhone,
   primaryColor,
   onSubmit,
+  enableTermsAndConditions,
+  termsAndConditionsText,
 }: IdentityFormProps) {
   const [name, setName] = useState("");
   const [email, setEmail] = useState("");
   const [phone, setPhone] = useState("");
+  const [termsChecked, setTermsChecked] = useState(false);
   const [errors, setErrors] = useState<Record<string, string>>({});
 
   const validate = useCallback(() => {
@@ -45,8 +50,18 @@ export function IdentityForm({
       !phone.trim()
     )
       e.contact = "Please provide either an email or phone number";
+    if (enableTermsAndConditions && !termsChecked)
+      e.terms = "You must accept the terms and conditions";
     return e;
-  }, [name, email, phone, collectEmail, collectPhone]);
+  }, [
+    name,
+    email,
+    phone,
+    collectEmail,
+    collectPhone,
+    enableTermsAndConditions,
+    termsChecked,
+  ]);
 
   const handleSubmit = useCallback(
     (ev: React.FormEvent) => {
@@ -123,6 +138,17 @@ export function IdentityForm({
       {errors.contact && (
         <div className={styles.formError}>{errors.contact}</div>
       )}
+      {enableTermsAndConditions && (
+        <label className={styles.termsLabel}>
+          <input
+            type="checkbox"
+            checked={termsChecked}
+            onChange={(ev) => setTermsChecked(ev.target.checked)}
+          />
+          <span>{termsAndConditionsText}</span>
+        </label>
+      )}
+      {errors.terms && <div className={styles.formError}>{errors.terms}</div>}
       <button
         type="submit"
         className={styles.formSubmitButton}

package/src/PolymorphWidget.tsx

@@ -1,7 +1,8 @@
 import { LiveKitRoom } from "@livekit/components-react";
 import { MantineProvider } from "@mantine/core";
 import "@mantine/core/styles.css";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { MediaDeviceFailure } from "livekit-client";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { RoomHandler } from "./RoomHandler";
 import styles from "./styles.module.css";
 import { buildWidgetTheme } from "./theme";
@@ -69,6 +70,17 @@ export function PolymorphWidget(props: WidgetConfig) {
     };
   }, [session.disconnect]);
 
+  const handleMediaDeviceFailure = useCallback(
+    (failure?: MediaDeviceFailure) => {
+      if (failure === MediaDeviceFailure.PermissionDenied) {
+        session.setError(
+          "Microphone access denied. Please allow mic access in your browser settings.",
+        );
+      }
+    },
+    [session.setError],
+  );
+
   const audio = useMemo(
     () =>
       session.isVoiceEnabled
@@ -125,6 +137,7 @@ export function PolymorphWidget(props: WidgetConfig) {
             video={false}
             style={{ display: "none" }}
             onDisconnected={session.disconnect}
+            onMediaDeviceFailure={handleMediaDeviceFailure}
           >
             <RoomHandler
               setRoom={session.setRoom}

package/src/WidgetPanel.tsx

@@ -1,5 +1,5 @@
 import type { Room } from "livekit-client";
-import { useCallback, useRef, useState } from "react";
+import { type ChangeEvent, useCallback, useRef, useState } from "react";
 import { ChatThread } from "./ChatThread";
 import { IdentityForm } from "./IdentityForm";
 import styles from "./styles.module.css";
@@ -122,6 +122,8 @@ interface WidgetPanelProps {
     toggleScreenShare: () => void;
     setRoom: (room: Room | null) => void;
     setUser: (user: WidgetUser) => void;
+    needsTermsAcceptance: boolean;
+    acceptTerms: () => void;
   };
   onClose: () => void;
   hidden?: boolean;
@@ -190,7 +192,12 @@ export function WidgetPanel({ session, onClose, hidden }: WidgetPanelProps) {
           collectEmail={session.identityCollection.collectEmail}
           collectPhone={session.identityCollection.collectPhone}
           primaryColor={primaryColor}
-          onSubmit={session.setUser}
+          onSubmit={(user) => {
+            session.setUser(user);
+            if (rc?.enableTermsAndConditions) session.acceptTerms();
+          }}
+          enableTermsAndConditions={rc?.enableTermsAndConditions}
+          termsAndConditionsText={rc?.termsAndConditionsText}
         />
       ) : (
         <>
@@ -213,6 +220,19 @@ export function WidgetPanel({ session, onClose, hidden }: WidgetPanelProps) {
           {session.error && (
             <div className={styles.errorText}>{session.error}</div>
           )}
+          {session.needsTermsAcceptance && rc?.termsAndConditionsText && (
+            <div className={styles.termsBar}>
+              <label className={styles.termsLabel}>
+                <input
+                  type="checkbox"
+                  onChange={(e: ChangeEvent<HTMLInputElement>) => {
+                    if (e.target.checked) session.acceptTerms();
+                  }}
+                />
+                <span>{rc.termsAndConditionsText}</span>
+              </label>
+            </div>
+          )}
           <div className={styles.inputBar}>
             <textarea
               ref={textareaRef}
@@ -226,14 +246,20 @@ export function WidgetPanel({ session, onClose, hidden }: WidgetPanelProps) {
               onChange={(e) => setInputValue(e.target.value)}
               onInput={handleInput}
               onKeyDown={handleKeyDown}
-              disabled={session.status === "connecting"}
+              disabled={
+                session.status === "connecting" || session.needsTermsAcceptance
+              }
               rows={1}
             />
             <button
               type="button"
               className={styles.iconButton}
               onClick={handleSend}
-              disabled={!inputValue.trim() || session.status === "connecting"}
+              disabled={
+                !inputValue.trim() ||
+                session.status === "connecting" ||
+                session.needsTermsAcceptance
+              }
             >
               <SendIcon />
             </button>

package/src/__tests__/IdentityForm.test.tsx

@@ -25,6 +25,13 @@ function renderForm(
   return { onSubmit };
 }
 
+function requireFormElement(element: HTMLFormElement | null): HTMLFormElement {
+  if (!element) {
+    throw new Error("Expected submit button to be inside a form");
+  }
+  return element;
+}
+
 describe("IdentityForm", () => {
   // ── Rendering ──
 
@@ -88,7 +95,9 @@ describe("IdentityForm", () => {
     });
     // Use fireEvent.submit to bypass native <input type="email"> validation in jsdom
     fireEvent.submit(
-      screen.getByRole("button", { name: "Start Chat" }).closest("form")!,
+      requireFormElement(
+        screen.getByRole("button", { name: "Start Chat" }).closest("form"),
+      ),
     );
     expect(screen.getByText("Invalid email format")).toBeInTheDocument();
     expect(onSubmit).not.toHaveBeenCalled();

package/src/__tests__/PolymorphWidget.test.tsx

@@ -45,6 +45,13 @@ const RESOLVE_RESPONSE = {
 
 let fetchMock: ReturnType<typeof vi.fn>;
 
+function requireElement<T>(element: T | null | undefined, message: string): T {
+  if (!element) {
+    throw new Error(message);
+  }
+  return element;
+}
+
 beforeEach(() => {
   fetchMock = vi.fn().mockImplementation((url: string) => {
     if (url.includes("/widget-configs/resolve")) {
@@ -77,7 +84,10 @@ describe("PolymorphWidget", () => {
 
   it("clicking FAB opens the panel", async () => {
     render(<PolymorphWidget apiBaseUrl="http://test" apiKey="key" />);
-    const fab = screen.getByTitle("Chat").closest("button")!;
+    const fab = requireElement(
+      screen.getByTitle("Chat").closest("button"),
+      "Expected chat button",
+    );
     fireEvent.click(fab);
     await waitFor(() => {
       expect(
@@ -88,7 +98,10 @@ describe("PolymorphWidget", () => {
 
   it("clicking FAB again closes the panel", async () => {
     render(<PolymorphWidget apiBaseUrl="http://test" apiKey="key" />);
-    const fab = screen.getByTitle("Chat").closest("button")!;
+    const fab = requireElement(
+      screen.getByTitle("Chat").closest("button"),
+      "Expected chat button",
+    );
 
     // Open
     fireEvent.click(fab);
@@ -102,8 +115,13 @@ describe("PolymorphWidget", () => {
     // (not the panel header close button) by its CSS class
     const fabButtons = screen
       .getAllByTitle("Close")
-      .map((el) => el.closest("button")!);
-    const fabBtn = fabButtons.find((btn) => btn.className.includes("fab"))!;
+      .map((el) =>
+        requireElement(el.closest("button"), "Expected close button"),
+      );
+    const fabBtn = requireElement(
+      fabButtons.find((btn) => btn.className.includes("fab")),
+      "Expected floating close button",
+    );
     fireEvent.click(fabBtn);
     await waitFor(() => {
       expect(
@@ -141,7 +159,10 @@ describe("PolymorphWidget", () => {
       expect(screen.getByText("Welcome!")).toBeInTheDocument();
     });
 
-    const root = document.querySelector(".polymorph-widget")!;
+    const root = requireElement(
+      document.querySelector(".polymorph-widget"),
+      "Expected widget root",
+    );
     expect(root.className).toContain("bottomLeft");
   });
 
@@ -167,7 +188,10 @@ describe("PolymorphWidget", () => {
       expect(screen.getByText("Welcome!")).toBeInTheDocument();
     });
 
-    const root = document.querySelector(".polymorph-widget")!;
-    expect((root as HTMLElement).style.colorScheme).toBe("dark");
+    const root = requireElement(
+      document.querySelector(".polymorph-widget"),
+      "Expected widget root",
+    );
+    expect(root.style.colorScheme).toBe("dark");
   });
 });

package/src/__tests__/usePolymorphSession.test.ts

@@ -14,6 +14,9 @@ const MOCK_CONFIG: ResolvedWidgetConfig = {
   greeting: "Hello!",
   collectEmail: "hidden",
   collectPhone: "hidden",
+  alwaysOn: false,
+  enableTermsAndConditions: false,
+  termsAndConditionsText: "",
 };
 
 function mockResolveResponse(cfg = MOCK_CONFIG) {
@@ -28,6 +31,9 @@ function mockResolveResponse(cfg = MOCK_CONFIG) {
     greeting: cfg.greeting,
     collect_email: cfg.collectEmail,
     collect_phone: cfg.collectPhone,
+    always_on: cfg.alwaysOn,
+    enable_terms_and_conditions: cfg.enableTermsAndConditions,
+    terms_and_conditions_text: cfg.termsAndConditionsText,
   };
 }
 

package/src/styles.module.css

@@ -421,6 +421,25 @@
   outline-offset: 2px;
 }
 
+.termsBar {
+  padding: 8px 16px;
+  border-top: 1px solid var(--mantine-color-default-border);
+  font-size: 12px;
+  color: var(--mantine-color-dimmed);
+}
+.termsLabel {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  font-size: 12px;
+  line-height: 1.4;
+  cursor: pointer;
+}
+.termsLabel input[type="checkbox"] {
+  margin-top: 2px;
+  flex-shrink: 0;
+}
+
 /* Mobile: full-width panel on small screens */
 @media (max-width: 420px) {
   .bottomRight,

package/src/types.ts

@@ -14,6 +14,8 @@ export interface WidgetConfig {
   fetchOptions?: RequestInit;
   /** Called when a session starts with room info for constructing join URLs. */
   onSessionStart?: (info: { roomId: string; joinToken: string }) => void;
+  /** Auto-capture behavioral events (page_view, idle, rage_click). Defaults to true. */
+  autoCapture?: boolean;
 }
 
 export interface WidgetUser {
@@ -37,6 +39,9 @@ export interface ResolvedWidgetConfig {
   greeting: string;
   collectEmail: FieldRequirement;
   collectPhone: FieldRequirement;
+  alwaysOn: boolean;
+  enableTermsAndConditions: boolean;
+  termsAndConditionsText: string;
 }
 
 export type FieldRequirement = "required" | "optional" | "hidden";
@@ -57,3 +62,22 @@ export interface ChatMessage {
 }
 
 export type SessionStatus = "idle" | "connecting" | "connected" | "error";
+
+export type WidgetEventType =
+  | "page_view"
+  | "click"
+  | "form_start"
+  | "form_abandon"
+  | "error_seen"
+  | "idle"
+  | "rage_click"
+  | "scroll_depth"
+  | "custom";
+
+export interface WidgetEvent {
+  type: WidgetEventType;
+  payload?: Record<string, unknown>;
+  url?: string;
+  element?: string;
+  timestamp: number;
+}

package/src/usePolymorphSession.ts

@@ -6,6 +6,8 @@ import type {
   ResolvedWidgetConfig,
   SessionStatus,
   WidgetConfig,
+  WidgetEvent,
+  WidgetEventType,
   WidgetUser,
 } from "./types";
 
@@ -21,6 +23,20 @@ function resolveApiBaseUrl(configured?: string): string {
   return "https://api.usepolymorph.com";
 }
 
+function uuid(): string {
+  if (
+    typeof crypto !== "undefined" &&
+    typeof crypto.randomUUID === "function"
+  ) {
+    // eslint-disable-next-line no-restricted-globals
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+  });
+}
+
 function storageKey(base: string, scope?: string): string {
   return scope ? `${base}:${scope}` : base;
 }
@@ -37,6 +53,17 @@ function loadStoredIdentity(scope?: string): WidgetUser | undefined {
   return undefined;
 }
 
+function loadTermsAccepted(scope?: string): boolean {
+  try {
+    return (
+      localStorage.getItem(storageKey("polymorph_tc_accepted", scope)) ===
+      "true"
+    );
+  } catch {
+    return false;
+  }
+}
+
 interface RoomConnection {
   token: string;
   livekitUrl: string;
@@ -87,6 +114,7 @@ function buildAuthHeaders(
 
 export function usePolymorphSession(config: WidgetConfig) {
   const apiBaseUrl = resolveApiBaseUrl(config.apiBaseUrl);
+  const autoCapture = config.autoCapture ?? true;
   // Scope storage keys so multiple widget instances don't collide.
   const scope = config.configId || config.apiKey;
   const [status, setStatus] = useState<SessionStatus>("idle");
@@ -106,8 +134,10 @@ export function usePolymorphSession(config: WidgetConfig) {
   const [resolvedUser, setResolvedUser] = useState<WidgetUser | undefined>(
     config.user ?? loadStoredIdentity(scope),
   );
+  const [termsAccepted, setTermsAccepted] = useState(loadTermsAccepted(scope));
   const roomRef = useRef<Room | null>(null);
   const pendingMessagesRef = useRef<string[]>([]);
+  const pendingEventsRef = useRef<WidgetEvent[]>([]);
   const isPanelOpenRef = useRef<boolean>(false);
   // Stable ref for fetchOptions to avoid infinite useEffect loops
   // (inline objects like { credentials: "include" } create new refs each render)
@@ -154,6 +184,9 @@ export function usePolymorphSession(config: WidgetConfig) {
           greeting: data.greeting,
           collectEmail: data.collect_email,
           collectPhone: data.collect_phone,
+          alwaysOn: data.always_on ?? false,
+          enableTermsAndConditions: data.enable_terms_and_conditions ?? false,
+          termsAndConditionsText: data.terms_and_conditions_text ?? "",
         };
         setResolvedConfig(cfg);
 
@@ -231,6 +264,44 @@ export function usePolymorphSession(config: WidgetConfig) {
     [scope],
   );
 
+  const acceptTerms = useCallback(() => {
+    setTermsAccepted(true);
+    try {
+      localStorage.setItem(storageKey("polymorph_tc_accepted", scope), "true");
+    } catch {
+      /* quota exceeded */
+    }
+  }, [scope]);
+
+  const needsTermsAcceptance =
+    resolvedConfig?.enableTermsAndConditions === true && !termsAccepted;
+
+  // Browser tab notification for unread messages
+  const originalTitleRef = useRef(
+    typeof document !== "undefined" ? document.title : "",
+  );
+  const [unreadCount, setUnreadCount] = useState(0);
+
+  useEffect(() => {
+    if (unreadCount === 0) {
+      document.title = originalTitleRef.current;
+      return;
+    }
+    const base = originalTitleRef.current;
+    let showNotification = true;
+    document.title = `(${unreadCount}) New message${unreadCount > 1 ? "s" : ""} - ${base}`;
+    const interval = setInterval(() => {
+      showNotification = !showNotification;
+      document.title = showNotification
+        ? `(${unreadCount}) New message${unreadCount > 1 ? "s" : ""} - ${base}`
+        : base;
+    }, 1500);
+    return () => {
+      clearInterval(interval);
+      document.title = base;
+    };
+  }, [unreadCount]);
+
   const addMessage = useCallback(
     (
       role: "user" | "agent",
@@ -242,11 +313,12 @@ export function usePolymorphSession(config: WidgetConfig) {
       if (role === "agent" && !isPanelOpenRef.current) {
         setHasUnread(true);
         setWiggleKey((k) => k + 1);
+        setUnreadCount((c) => c + 1);
       }
       setMessages((prev) => [
         ...prev,
         {
-          id: crypto.randomUUID(),
+          id: uuid(),
           role,
           text,
           source,
@@ -261,12 +333,14 @@ export function usePolymorphSession(config: WidgetConfig) {
 
   const clearUnread = useCallback(() => {
     setHasUnread(false);
+    setUnreadCount(0);
   }, []);
 
   const setPanelOpen = useCallback((open: boolean) => {
     isPanelOpenRef.current = open;
     if (open) {
       setHasUnread(false);
+      setUnreadCount(0);
     }
   }, []);
 
@@ -292,7 +366,7 @@ export function usePolymorphSession(config: WidgetConfig) {
       const sessionKey = storageKey("polymorph_widget_session", scope);
       let externalUserId = localStorage.getItem(sessionKey) ?? undefined;
       if (!externalUserId) {
-        externalUserId = `widget-session-${crypto.randomUUID().slice(0, 12)}`;
+        externalUserId = `widget-session-${uuid().slice(0, 12)}`;
         localStorage.setItem(sessionKey, externalUserId);
       }
 
@@ -339,6 +413,13 @@ export function usePolymorphSession(config: WidgetConfig) {
     }
   }, [config, status, resolvedUser, resolvedConfig, apiBaseUrl, scope]);
 
+  // Auto-connect when always-on mode is enabled
+  useEffect(() => {
+    if (resolvedConfig?.alwaysOn && status === "idle") {
+      void connect();
+    }
+  }, [resolvedConfig?.alwaysOn, status, connect]);
+
   const disconnect = useCallback(() => {
     roomRef.current?.disconnect();
     roomRef.current = null;
@@ -380,8 +461,12 @@ export function usePolymorphSession(config: WidgetConfig) {
       const newState = !room.localParticipant.isMicrophoneEnabled;
       await room.localParticipant.setMicrophoneEnabled(newState);
       setIsMicActive(newState);
-    } catch {
-      /* mic toggle failed — ignore */
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "NotAllowedError") {
+        setError(
+          "Microphone access denied. Please allow mic access in your browser settings.",
+        );
+      }
     }
   }, []);
 
@@ -406,8 +491,14 @@ export function usePolymorphSession(config: WidgetConfig) {
         reliable: true,
         topic: "voice_mode",
       });
-    } catch {
-      /* voice toggle failed — ignore */
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "NotAllowedError") {
+        setError(
+          "Microphone access denied. Please allow mic access in your browser settings.",
+        );
+        setIsVoiceEnabled(false);
+        setIsMicActive(false);
+      }
     }
   }, [isVoiceEnabled, connect]);
 
@@ -423,6 +514,76 @@ export function usePolymorphSession(config: WidgetConfig) {
     }
   }, []);
 
+  const emitEvent = useCallback(
+    (type: WidgetEventType, payload?: Record<string, unknown>) => {
+      const event: WidgetEvent = {
+        type,
+        payload,
+        url: typeof window !== "undefined" ? window.location.href : undefined,
+        timestamp: Date.now(),
+      };
+      const room = roomRef.current;
+      if (room) {
+        const data = new TextEncoder().encode(JSON.stringify(event));
+        room.localParticipant.publishData(data, {
+          reliable: true,
+          topic: "widget_event",
+        });
+      } else {
+        pendingEventsRef.current.push(event);
+      }
+    },
+    [],
+  );
+
+  // Auto-capture: page_view on mount
+  useEffect(() => {
+    if (!autoCapture) return;
+    emitEvent("page_view", {
+      referrer: typeof document !== "undefined" ? document.referrer : "",
+    });
+  }, [autoCapture, emitEvent]);
+
+  // Auto-capture: idle detection (30s no interaction)
+  useEffect(() => {
+    if (!autoCapture) return;
+    let timer: ReturnType<typeof setTimeout>;
+    const reset = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => emitEvent("idle"), 30_000);
+    };
+    const events = ["mousemove", "keydown", "click", "scroll", "touchstart"];
+    for (const e of events)
+      window.addEventListener(e, reset, { passive: true });
+    reset();
+    return () => {
+      clearTimeout(timer);
+      for (const e of events) window.removeEventListener(e, reset);
+    };
+  }, [autoCapture, emitEvent]);
+
+  // Auto-capture: rage click (3+ clicks on same target within 1s)
+  useEffect(() => {
+    if (!autoCapture) return;
+    const clicks: { target: EventTarget | null; time: number }[] = [];
+    const onClick = (e: MouseEvent) => {
+      const now = Date.now();
+      clicks.push({ target: e.target, time: now });
+      while (clicks.length > 0 && now - clicks[0].time > 1000) clicks.shift();
+      const sameTarget = clicks.filter((c) => c.target === e.target);
+      if (sameTarget.length >= 3) {
+        const el = e.target as HTMLElement | null;
+        emitEvent("rage_click", {
+          element: el?.tagName?.toLowerCase(),
+          text: el?.textContent?.slice(0, 100),
+        });
+        clicks.length = 0;
+      }
+    };
+    window.addEventListener("click", onClick);
+    return () => window.removeEventListener("click", onClick);
+  }, [autoCapture, emitEvent]);
+
   const setRoom = useCallback((room: Room | null) => {
     roomRef.current = room;
     if (room) {
@@ -439,6 +600,16 @@ export function usePolymorphSession(config: WidgetConfig) {
       room.on(RoomEvent.ParticipantConnected, checkObserver);
       room.on(RoomEvent.ParticipantDisconnected, checkObserver);
 
+      // Flush pending widget events
+      const pendingEvents = pendingEventsRef.current.splice(0);
+      for (const event of pendingEvents) {
+        const data = new TextEncoder().encode(JSON.stringify(event));
+        room.localParticipant.publishData(data, {
+          reliable: true,
+          topic: "widget_event",
+        });
+      }
+
       // Flush pending messages once the agent participant has joined the room.
       // LiveKit data messages are only delivered to participants currently in
       // the room, so sending before the agent connects means messages are lost.
@@ -498,5 +669,9 @@ export function usePolymorphSession(config: WidgetConfig) {
     setUser,
     clearUnread,
     setPanelOpen,
+    emitEvent,
+    setError,
+    needsTermsAcceptance,
+    acceptTerms,
   };
 }