polymorph-sdk 0.2.0 → 0.2.3

package/src/types.ts

@@ -1,17 +1,30 @@
 export interface WidgetConfig {
   apiBaseUrl: string;
   apiKey?: string;
-  metadata?: Record<string, string>;
+  /** Server-side widget config ID. When set, metadata is ignored and config is resolved server-side. */
+  configId?: string;
+  /** LiveKit dispatched agent name (default: "custom-voice-agent"). */
+  agentName?: string;
+  metadata?: Record<string, string | string[]>;
+  /** Pre-filled user identity. When provided, the agent skips asking for these fields. */
+  user?: WidgetUser;
   branding?: WidgetBranding;
   position?: "bottom-right" | "bottom-left";
   /** Enable voice call (default: true). When false, widget is chat-only. */
   enableVoice?: boolean;
-  /** Participant identity sent to LiveKit */
-  userIdentity?: string;
-  /** Participant display name sent to LiveKit */
-  userName?: string;
   /** Extra options passed to fetch (e.g. { credentials: "include" }) */
   fetchOptions?: RequestInit;
+  /** Render widget in dark mode (default: false) */
+  darkMode?: boolean;
+}
+
+export interface WidgetUser {
+  /** Display name (e.g. "Jane Smith") */
+  name?: string;
+  /** Email address */
+  email?: string;
+  /** Phone number */
+  phone?: string;
 }
 
 export interface WidgetBranding {

package/src/usePolymorphSession.ts

@@ -1,56 +1,117 @@
-import { useCallback, useRef, useState } from "react";
 import type { Room } from "livekit-client";
+import { useCallback, useEffect, useRef, useState } from "react";
 import type { ChatMessage, SessionStatus, WidgetConfig } from "./types";
 
+const csrfStorageKey = "polymorph.csrf";
+
 interface RoomConnection {
   token: string;
   livekitUrl: string;
 }
 
-function makeGreeting(text: string): ChatMessage {
-  return {
-    id: "greeting",
-    role: "agent",
-    text,
-    source: "chat",
-    timestamp: Date.now(),
-  };
+async function ensureCsrf(apiBaseUrl: string, fetchOptions?: RequestInit) {
+  if (sessionStorage.getItem(csrfStorageKey)) return;
+
+  try {
+    const res = await fetch(`${apiBaseUrl}/auth/csrf`, {
+      credentials: "include",
+      ...(fetchOptions ?? {}),
+    });
+    if (!res.ok) {
+      throw new Error(`CSRF request failed (${res.status})`);
+    }
+    const data = (await res.json()) as { csrf_token?: string };
+    if (data.csrf_token) {
+      sessionStorage.setItem(csrfStorageKey, data.csrf_token);
+      return;
+    }
+    throw new Error("CSRF token missing in response");
+  } catch (err) {
+    const message =
+      err instanceof Error ? err.message : "Failed to fetch CSRF token";
+    throw new Error(message);
+  }
 }
 
 export function usePolymorphSession(config: WidgetConfig) {
+  const isChatOnlyAgent = (config.agentName || "")
+    .toLowerCase()
+    .includes("chat-agent");
+  const defaultVoiceEnabled = config.enableVoice !== false && !isChatOnlyAgent;
   const [status, setStatus] = useState<SessionStatus>("idle");
-  const [roomConnection, setRoomConnection] = useState<RoomConnection | null>(null);
-  const [messages, setMessages] = useState<ChatMessage[]>(() => {
-    if (config.branding?.greeting) {
-      return [makeGreeting(config.branding.greeting)];
-    }
-    return [];
-  });
-  const [isVoiceEnabled, setIsVoiceEnabled] = useState(config.enableVoice !== false);
-  const [isMicActive, setIsMicActive] = useState(config.enableVoice !== false);
+  const [roomConnection, setRoomConnection] = useState<RoomConnection | null>(
+    null,
+  );
+  const greeting = config.branding?.greeting;
+  const [messages, setMessages] = useState<ChatMessage[]>(() =>
+    greeting
+      ? [
+          {
+            id: "greeting",
+            role: "agent" as const,
+            text: greeting,
+            source: "chat" as const,
+            timestamp: Date.now(),
+          },
+        ]
+      : [],
+  );
+  const [isVoiceEnabled, setIsVoiceEnabled] = useState(defaultVoiceEnabled);
+  const [isMicActive, setIsMicActive] = useState(defaultVoiceEnabled);
   const [error, setError] = useState<string | null>(null);
   const roomRef = useRef<Room | null>(null);
+  const pendingMessagesRef = useRef<string[]>([]);
 
-  const addMessage = useCallback((role: "user" | "agent", text: string, source: "chat" | "voice") => {
-    setMessages(prev => [...prev, {
-      id: crypto.randomUUID(),
-      role,
-      text,
-      source,
-      timestamp: Date.now(),
-    }]);
-  }, []);
+  useEffect(() => {
+    setIsVoiceEnabled(defaultVoiceEnabled);
+    setIsMicActive(defaultVoiceEnabled);
+    if (roomRef.current) {
+      void roomRef.current.localParticipant.setMicrophoneEnabled(
+        defaultVoiceEnabled,
+      );
+    }
+  }, [defaultVoiceEnabled]);
+
+  const addMessage = useCallback(
+    (role: "user" | "agent", text: string, source: "chat" | "voice") => {
+      setMessages((prev) => [
+        ...prev,
+        {
+          id: crypto.randomUUID(),
+          role,
+          text,
+          source,
+          timestamp: Date.now(),
+        },
+      ]);
+    },
+    [],
+  );
 
   const connect = useCallback(async () => {
     if (status === "connecting" || status === "connected") return;
     setStatus("connecting");
     setError(null);
     try {
-      const { headers: extraHeaders, ...restFetchOptions } = config.fetchOptions ?? {};
+      const { headers: extraHeaders, ...restFetchOptions } =
+        config.fetchOptions ?? {};
       const authHeaders: Record<string, string> = {};
       if (config.apiKey) {
-        authHeaders["Authorization"] = `Bearer ${config.apiKey}`;
+        authHeaders.Authorization = `Bearer ${config.apiKey}`;
+      } else if (restFetchOptions.credentials === "include") {
+        await ensureCsrf(config.apiBaseUrl, restFetchOptions);
+        const csrf = sessionStorage.getItem(csrfStorageKey);
+        if (csrf) authHeaders["x-csrf-token"] = csrf;
+      }
+
+      // Persist a stable external_user_id per browser for session stitching.
+      const storageKey = "polymorph_widget_session";
+      let externalUserId = localStorage.getItem(storageKey) ?? undefined;
+      if (!externalUserId) {
+        externalUserId = `widget-session-${crypto.randomUUID().slice(0, 12)}`;
+        localStorage.setItem(storageKey, externalUserId);
       }
+
       const response = await fetch(`${config.apiBaseUrl}/voice-rooms/start`, {
         method: "POST",
         headers: {
@@ -61,15 +122,29 @@ export function usePolymorphSession(config: WidgetConfig) {
             : extraHeaders),
         },
         body: JSON.stringify({
-          agent_name: "custom-voice-agent",
-          metadata: config.metadata,
-          user_identity: config.userIdentity,
-          user_name: config.userName,
+          agent_name: config.agentName || "custom-voice-agent",
+          config_id: config.configId ?? undefined,
+          metadata: config.configId
+            ? undefined
+            : {
+                ...config.metadata,
+                ...(config.branding?.greeting && {
+                  greeting: config.branding.greeting,
+                }),
+                ...(config.user?.name && { user_name: config.user.name }),
+                ...(config.user?.email && { user_email: config.user.email }),
+                ...(config.user?.phone && { user_phone: config.user.phone }),
+              },
+          user_name: config.user?.name,
+          external_user_id: externalUserId,
         }),
         ...restFetchOptions,
       });
+      if (response.status === 403) {
+        sessionStorage.removeItem(csrfStorageKey);
+      }
       if (!response.ok) {
-        throw new Error(await response.text() || "Failed to start session");
+        throw new Error((await response.text()) || "Failed to start session");
       }
       const data = await response.json();
       setRoomConnection({ token: data.token, livekitUrl: data.livekit_url });
@@ -86,13 +161,28 @@ export function usePolymorphSession(config: WidgetConfig) {
     setStatus("idle");
   }, []);
 
-  const sendMessage = useCallback((text: string) => {
-    const room = roomRef.current;
-    if (!room || !text.trim()) return;
-    addMessage("user", text.trim(), "chat");
-    const payload = new TextEncoder().encode(JSON.stringify({ text: text.trim() }));
-    room.localParticipant.publishData(payload, { reliable: true, topic: "chat_message" });
-  }, [addMessage]);
+  const sendMessage = useCallback(
+    (text: string) => {
+      if (!text.trim()) return;
+      const trimmed = text.trim();
+      addMessage("user", trimmed, "chat");
+
+      const room = roomRef.current;
+      if (room) {
+        const payload = new TextEncoder().encode(
+          JSON.stringify({ text: trimmed }),
+        );
+        room.localParticipant.publishData(payload, {
+          reliable: true,
+          topic: "chat_message",
+        });
+      } else {
+        pendingMessagesRef.current.push(trimmed);
+        void connect();
+      }
+    },
+    [addMessage, connect],
+  );
 
   const toggleMic = useCallback(async () => {
     const room = roomRef.current;
@@ -109,11 +199,29 @@ export function usePolymorphSession(config: WidgetConfig) {
     await room.localParticipant.setMicrophoneEnabled(newState);
     setIsVoiceEnabled(newState);
     setIsMicActive(newState);
+    const payload = new TextEncoder().encode(
+      JSON.stringify({ voice_enabled: newState }),
+    );
+    room.localParticipant.publishData(payload, {
+      reliable: true,
+      topic: "voice_mode",
+    });
   }, [isVoiceEnabled]);
 
   const setRoom = useCallback((room: Room | null) => {
     roomRef.current = room;
-    if (room) setStatus("connected");
+    if (room) {
+      setStatus("connected");
+      // Flush any messages queued before the room was ready
+      const pending = pendingMessagesRef.current.splice(0);
+      for (const text of pending) {
+        const payload = new TextEncoder().encode(JSON.stringify({ text }));
+        room.localParticipant.publishData(payload, {
+          reliable: true,
+          topic: "chat_message",
+        });
+      }
+    }
   }, []);
 
   return {