polymorph-sdk 0.1.0 → 0.2.2

package/src/index.ts

@@ -0,0 +1,8 @@
+export { PolymorphWidget } from "./PolymorphWidget";
+export type {
+  ChatMessage,
+  SessionStatus,
+  WidgetBranding,
+  WidgetConfig,
+} from "./types";
+export { usePolymorphSession } from "./usePolymorphSession";

package/src/styles.module.css

@@ -0,0 +1,304 @@
+.widgetRoot {
+  position: fixed;
+  z-index: 9999;
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  justify-content: flex-end;
+  gap: 12px;
+  pointer-events: none;
+}
+
+.bottomRight {
+  top: 24px;
+  bottom: 24px;
+  right: 24px;
+}
+
+.bottomLeft {
+  top: 24px;
+  bottom: 24px;
+  left: 24px;
+  align-items: flex-start;
+}
+
+.fab {
+  width: 56px;
+  height: 56px;
+  border-radius: 28px;
+  border: none;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+  transition:
+    transform 150ms ease,
+    box-shadow 150ms ease;
+  color: white;
+  pointer-events: auto;
+}
+
+.fab:hover {
+  transform: scale(1.05);
+  box-shadow: 0 6px 16px rgba(0, 0, 0, 0.2);
+}
+
+.panel {
+  width: 380px;
+  max-height: 600px;
+  display: flex;
+  flex-direction: column;
+  border-radius: 16px;
+  box-shadow:
+    0 4px 24px rgba(0, 0, 0, 0.08),
+    0 12px 48px rgba(0, 0, 0, 0.12);
+  overflow: hidden;
+  background: var(--mantine-color-body);
+  color: var(--mantine-color-text);
+  pointer-events: auto;
+}
+
+.header {
+  padding: 16px 16px 12px;
+  border-bottom: 1px solid var(--mantine-color-default-border);
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+}
+
+.chatThread {
+  flex: 1;
+  overflow-y: auto;
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 200px;
+  max-height: 400px;
+}
+
+.messageBubble {
+  max-width: 80%;
+  padding: 8px 12px;
+  border-radius: 12px;
+  font-size: 14px;
+  line-height: 1.4;
+  word-wrap: break-word;
+}
+
+.agentMessage {
+  align-self: flex-start;
+  background: var(--mantine-color-gray-light);
+  color: var(--mantine-color-text);
+}
+
+.userMessage {
+  align-self: flex-end;
+  color: white;
+}
+
+.voiceLabel {
+  font-size: 10px;
+  opacity: 0.6;
+  margin-top: 2px;
+}
+
+.voiceOverlay {
+  padding: 8px 16px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+  color: var(--mantine-color-dimmed);
+  border-top: 1px solid var(--mantine-color-default-border);
+}
+
+.voiceBars {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  height: 16px;
+}
+
+.voiceBar {
+  width: 3px;
+  border-radius: 2px;
+  background: #22c55e;
+  animation: voiceBar 1.2s ease-in-out infinite;
+}
+
+.voiceBar:nth-child(1) {
+  height: 6px;
+  animation-delay: 0s;
+}
+.voiceBar:nth-child(2) {
+  height: 12px;
+  animation-delay: 0.2s;
+}
+.voiceBar:nth-child(3) {
+  height: 8px;
+  animation-delay: 0.4s;
+}
+
+@keyframes voiceBar {
+  0%,
+  100% {
+    transform: scaleY(1);
+  }
+  50% {
+    transform: scaleY(0.4);
+  }
+}
+
+.voiceToggle {
+  margin-left: auto;
+  width: 28px;
+  height: 28px;
+  border-radius: 14px;
+  border: 1px solid var(--mantine-color-default-border);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--mantine-color-gray-light);
+  color: var(--mantine-color-dimmed);
+  transition: all 150ms ease;
+}
+
+.voiceToggle:hover {
+  background: var(--mantine-color-gray-light-hover);
+}
+
+.voiceToggleActive {
+  background: light-dark(#dcfce7, #1a3a2a);
+  border-color: light-dark(#bbf7d0, #2a5a3a);
+  color: light-dark(#16a34a, #4ade80);
+}
+
+.voiceToggleActive:hover {
+  background: light-dark(#bbf7d0, #2a5a3a);
+}
+
+.inputBar {
+  padding: 12px 16px;
+  border-top: 1px solid var(--mantine-color-default-border);
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.inputField {
+  flex: 1;
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: 8px;
+  padding: 8px 12px;
+  font-size: 14px;
+  outline: none;
+  font-family: inherit;
+  background: var(--mantine-color-body);
+  color: var(--mantine-color-text);
+}
+
+.inputField:focus {
+  border-color: var(--mantine-color-dimmed);
+}
+
+.iconButton {
+  width: 36px;
+  height: 36px;
+  border-radius: 8px;
+  border: none;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  color: var(--mantine-color-dimmed);
+  transition:
+    background 150ms ease,
+    color 150ms ease;
+}
+
+.iconButton:hover {
+  background: var(--mantine-color-gray-light);
+}
+
+.iconButton:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.iconButtonActive {
+  color: #22c55e;
+}
+
+.connectButton {
+  margin: 16px;
+  padding: 10px 20px;
+  border-radius: 8px;
+  border: none;
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 500;
+  color: white;
+  transition: opacity 150ms ease;
+}
+
+.connectButton:hover {
+  opacity: 0.9;
+}
+
+.connectButton:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.statusBadge {
+  font-size: 11px;
+  padding: 2px 8px;
+  border-radius: 10px;
+  font-weight: 500;
+}
+
+.errorText {
+  color: #dc2626;
+  font-size: 13px;
+  padding: 0 16px;
+}
+
+.thinkingDots {
+  display: flex;
+  gap: 4px;
+  align-items: center;
+  height: 20px;
+}
+
+.thinkingDots span {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--mantine-color-dimmed);
+  animation: thinkingDot 1.4s ease-in-out infinite;
+}
+
+.thinkingDots span:nth-child(2) {
+  animation-delay: 0.2s;
+}
+
+.thinkingDots span:nth-child(3) {
+  animation-delay: 0.4s;
+}
+
+@keyframes thinkingDot {
+  0%,
+  80%,
+  100% {
+    opacity: 0.3;
+    transform: scale(0.8);
+  }
+  40% {
+    opacity: 1;
+    transform: scale(1);
+  }
+}

package/src/theme.ts

@@ -0,0 +1,53 @@
+import type { MantineColorsTuple, MantineThemeOverride } from "@mantine/core";
+import { createTheme } from "@mantine/core";
+
+function hexToMantineTuple(hex: string): MantineColorsTuple {
+  const r = Number.parseInt(hex.slice(1, 3), 16);
+  const g = Number.parseInt(hex.slice(3, 5), 16);
+  const b = Number.parseInt(hex.slice(5, 7), 16);
+
+  const lighten = (amt: number) =>
+    `#${[r, g, b]
+      .map((c) =>
+        Math.min(255, Math.round(c + (255 - c) * amt))
+          .toString(16)
+          .padStart(2, "0"),
+      )
+      .join("")}`;
+
+  const darken = (amt: number) =>
+    `#${[r, g, b]
+      .map((c) =>
+        Math.max(0, Math.round(c * (1 - amt)))
+          .toString(16)
+          .padStart(2, "0"),
+      )
+      .join("")}`;
+
+  return [
+    lighten(0.92),
+    lighten(0.84),
+    lighten(0.72),
+    lighten(0.56),
+    lighten(0.36),
+    hex,
+    darken(0.08),
+    darken(0.16),
+    darken(0.28),
+    darken(0.4),
+  ];
+}
+
+export function buildWidgetTheme(
+  primaryColor = "#171717",
+): MantineThemeOverride {
+  return createTheme({
+    fontFamily:
+      '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+    primaryColor: "brand",
+    colors: {
+      brand: hexToMantineTuple(primaryColor),
+    },
+    defaultRadius: "md",
+  });
+}

package/src/types.ts

@@ -0,0 +1,36 @@
+export interface WidgetConfig {
+  apiBaseUrl: string;
+  apiKey?: string;
+  /** LiveKit dispatched agent name (default: "custom-voice-agent"). */
+  agentName?: string;
+  metadata?: Record<string, string | string[]>;
+  branding?: WidgetBranding;
+  position?: "bottom-right" | "bottom-left";
+  /** Enable voice call (default: true). When false, widget is chat-only. */
+  enableVoice?: boolean;
+  /** Extra options passed to fetch (e.g. { credentials: "include" }) */
+  fetchOptions?: RequestInit;
+  /** Render widget in dark mode (default: false) */
+  darkMode?: boolean;
+}
+
+export interface WidgetBranding {
+  /** FAB and accent color (default: "#171717") */
+  primaryColor?: string;
+  /** Panel header title (default: "Hi there") */
+  title?: string;
+  /** Panel subheader */
+  subtitle?: string;
+  /** Initial message shown before agent connects */
+  greeting?: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: "user" | "agent";
+  text: string;
+  source: "chat" | "voice";
+  timestamp: number;
+}
+
+export type SessionStatus = "idle" | "connecting" | "connected" | "error";

package/src/usePolymorphSession.ts

@@ -0,0 +1,203 @@
+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;
+}
+
+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[]>([]);
+  const [isVoiceEnabled, setIsVoiceEnabled] = useState(defaultVoiceEnabled);
+  const [isMicActive, setIsMicActive] = useState(defaultVoiceEnabled);
+  const [error, setError] = useState<string | null>(null);
+  const roomRef = useRef<Room | null>(null);
+
+  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 authHeaders: Record<string, string> = {};
+      if (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: {
+          "Content-Type": "application/json",
+          ...authHeaders,
+          ...(extraHeaders instanceof Headers
+            ? Object.fromEntries(extraHeaders.entries())
+            : extraHeaders),
+        },
+        body: JSON.stringify({
+          agent_name: config.agentName || "custom-voice-agent",
+          metadata: {
+            ...config.metadata,
+            ...(config.branding?.greeting && {
+              greeting: config.branding.greeting,
+            }),
+          },
+          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");
+      }
+      const data = await response.json();
+      setRoomConnection({ token: data.token, livekitUrl: data.livekit_url });
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Something went wrong");
+      setStatus("error");
+    }
+  }, [config, status]);
+
+  const disconnect = useCallback(() => {
+    roomRef.current?.disconnect();
+    roomRef.current = null;
+    setRoomConnection(null);
+    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 toggleMic = useCallback(async () => {
+    const room = roomRef.current;
+    if (!room) return;
+    const newState = !isMicActive;
+    await room.localParticipant.setMicrophoneEnabled(newState);
+    setIsMicActive(newState);
+  }, [isMicActive]);
+
+  const toggleVoice = useCallback(async () => {
+    const room = roomRef.current;
+    if (!room) return;
+    const newState = !isVoiceEnabled;
+    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");
+  }, []);
+
+  return {
+    status,
+    roomConnection,
+    messages,
+    isVoiceEnabled,
+    isMicActive,
+    error,
+    connect,
+    disconnect,
+    addMessage,
+    sendMessage,
+    toggleMic,
+    toggleVoice,
+    setRoom,
+  };
+}