goji-search 2.0.8 → 3.0.1

package/README.md

@@ -1,5 +1,20 @@
 # Goji Search
 
+AI-powered chat widget for websites. Embeddable as a React component, Web Component, or vanilla JS widget.
+
+## Features
+
+- Real-time streaming chat via WebSocket
+- Multi-tenant support with company-specific branding
+- Returning visitor detection and personalized welcome messages
+- Idle re-engagement prompts
+- Deep analysis cards (ROI, comparisons, cost breakdowns)
+- CTA cards with calendar booking and email capture
+- Multi-language support (EN, FR, IT, ES, DE)
+- Voice transcription
+- Shadow DOM style isolation for embedding
+- Gated debug logging
+
 ## Installation
 
 ```bash
@@ -8,16 +23,77 @@ npm install goji-search
 yarn add goji-search
 ```
 
-## Usage
+## Quick Start
+
+### React
 
 ```tsx
 import { GojiSearchComponent } from 'goji-search';
 
 function App() {
   return (
-    <div>
-      <GojiSearchComponent /* props here */ />
-    </div>
+    <GojiSearchComponent
+      companyId="your-company-id"
+      apiKey="goji_yourcompany_prod_xxx"
+      apiUrl="https://api.getgoji.ai"
+    />
   );
 }
-```
+```
+
+### HTML / Vanilla JS
+
+```html
+<script src="https://cdn.getgoji.ai/widget.js"></script>
+<script>
+  GojiWidget.init({
+    companyId: 'your-company-id',
+    apiKey: 'goji_yourcompany_prod_xxx',
+    apiUrl: 'https://api.getgoji.ai'
+  });
+</script>
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `companyId` | `string` | Yes | Your company identifier |
+| `apiKey` | `string` | Yes | Your Goji API key |
+| `apiUrl` | `string` | No | Backend API URL (default: `http://localhost:8000`) |
+| `aiColor` | `string` | No | AI avatar color in HEX (falls back to brand color from company theme) |
+| `userMessageBackgroundColor` | `string` | No | User message bubble background color |
+
+## Exports
+
+```tsx
+// React component and error boundary
+import { GojiSearchComponent, GojiSearchErrorBoundary } from 'goji-search';
+
+// API client
+import { GojiSearchClient, createGojiClient } from 'goji-search';
+
+// Hooks
+import { useReturningVisitor, useVisitorId } from 'goji-search';
+
+// UTM and visitor utilities
+import { captureVisitorContext, getVisitorContext, getOrCreateVisitorId } from 'goji-search';
+```
+
+## Development
+
+```bash
+npm install          # Install dependencies
+npm run dev          # Development server
+npm run build        # Build React library + widget bundle
+npm run lint         # Lint
+npm run test         # Run tests (watch mode)
+npm run test:run     # Run tests once
+npm run test:coverage # Run tests with coverage
+```
+
+## Documentation
+
+See [USAGE.md](./USAGE.md) for detailed documentation, advanced usage, and API reference.
+
+See [CHANGELOG.md](./CHANGELOG.md) for version history.

package/dist/goji-search/components/elements/action-buttons.d.ts

@@ -4,10 +4,11 @@ interface ActionButtonsProps {
     isStreaming: boolean;
     searchQuery: string;
     isRecording?: boolean;
+    hideCalendar?: boolean;
     onSubmit: () => void;
     onVoiceSearch: () => void;
     onClose: () => void;
     onCalendarClick: () => void;
 }
-export declare function ActionButtons({ size, isHovered, isStreaming, searchQuery, isRecording, onSubmit, onVoiceSearch, onClose, onCalendarClick, }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function ActionButtons({ size, isHovered, isStreaming, searchQuery, isRecording, hideCalendar, onSubmit, onVoiceSearch, onClose, onCalendarClick, }: ActionButtonsProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/goji-search/components/elements/calendar-integration.d.ts

@@ -1,4 +1,5 @@
 interface CalendarIntegrationProps {
+    calLink?: string;
     onBooked?: () => void;
 }
 export default function CalendarIntegration(props?: CalendarIntegrationProps): import("react/jsx-runtime").JSX.Element;

package/dist/goji-search/components/elements/choice-bubbles.d.ts

@@ -0,0 +1,15 @@
+/**
+ * ChoiceBubbles Component
+ *
+ * Renders interactive choice buttons for guided conversations.
+ * When clicked, the selected choice is sent as the user's next message.
+ */
+interface ChoiceBubblesProps {
+    choices: string[];
+    onChoiceClick: (choice: string) => void;
+    disabled?: boolean;
+    variant?: "default" | "faded" | "dark";
+    aiColor?: string;
+}
+export declare function ChoiceBubbles({ choices, onChoiceClick, disabled, variant, aiColor, }: ChoiceBubblesProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/goji-search/components/elements/deep-analysis-card.d.ts

@@ -0,0 +1,16 @@
+export type AnalysisType = "roi" | "comparison" | "cost_breakdown" | "key_metrics";
+export type ConfidenceLevel = "high" | "medium" | "low";
+export interface DeepAnalysisData {
+    analysis_type: AnalysisType;
+    data: Record<string, any>;
+    confidence: ConfidenceLevel;
+    data_source_note: string;
+    generated_at?: number;
+}
+export interface DeepAnalysisCardProps {
+    analysisType: AnalysisType;
+    data?: DeepAnalysisData;
+    isLoading?: boolean;
+    onCollapse?: () => void;
+}
+export declare function DeepAnalysisCard({ analysisType, data, isLoading, onCollapse, }: DeepAnalysisCardProps): import("react/jsx-runtime").JSX.Element;

package/dist/goji-search/components/elements/email-input-box.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Email Input Box Component
+ *
+ * Displays a dedicated email input box when the backend requests email collection.
+ * - Appears below follow-up questions (after ClosingCard if present)
+ * - Includes email validation
+ * - Animated entrance/exit
+ * - Respects localized prompt text from backend
+ */
+interface EmailInputBoxProps {
+    /** Localized prompt text from backend */
+    promptText: string;
+    /** Session ID for submission */
+    sessionId?: string;
+    /** Callback when email is submitted */
+    onSubmit: (email: string) => Promise<void>;
+    /** Callback when user dismisses the box */
+    onDismiss?: () => void;
+    /** Additional CSS class */
+    className?: string;
+}
+export declare function EmailInputBox({ promptText, sessionId, onSubmit, onDismiss, className, }: EmailInputBoxProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/goji-search/components/elements/expandable-section.d.ts

@@ -0,0 +1,7 @@
+interface ExpandableSectionProps {
+    title: string;
+    children: React.ReactNode;
+    defaultExpanded?: boolean;
+}
+export declare function ExpandableSection({ title, children, defaultExpanded }: ExpandableSectionProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/goji-search/components/elements/inspiration-menu.d.ts

@@ -1,11 +1,14 @@
-import type { ReactNode } from "react";
 interface InspirationMenuProps {
     questions: string[];
     onQuestionClick: (question: string) => void;
     onClose: () => void;
     suggestedLabel?: string;
-    languageSelector?: ReactNode;
+    showLanguageSelector?: boolean;
+    supportedLanguages?: string[];
+    currentLanguage?: string;
+    onLanguageChange?: (lang: string) => void;
+    languageLabels?: Record<string, string>;
     color?: string;
 }
-export declare function InspirationMenu({ questions, onQuestionClick, onClose, suggestedLabel, languageSelector, color }: InspirationMenuProps): import("react/jsx-runtime").JSX.Element;
+export declare function InspirationMenu({ questions, onQuestionClick, onClose, suggestedLabel, showLanguageSelector, supportedLanguages, currentLanguage, onLanguageChange, languageLabels, color }: InspirationMenuProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/goji-search/components/elements/message-list.d.ts

@@ -11,6 +11,11 @@ interface Message {
     content: string;
     timestamp: number;
     sources?: ChatSource[];
+    isReengagement?: boolean;
+    choices?: string[];
+    choicesSelected?: boolean;
+    choicesVariant?: "default" | "faded" | "dark";
+    choiceMode?: "send" | "action";
 }
 interface MessageListProps {
     messages: Message[];
@@ -18,7 +23,9 @@ interface MessageListProps {
     aiAvatarSrc?: string;
     size?: "m" | "l" | "xl" | "s" | "xs";
     brandName?: string;
-    userBackgroundColor?: string;
+    onChoiceClick?: (messageIndex: number, choice: string) => void;
+    userMessageBackgroundColor?: string;
+    aiColor?: string;
 }
-export declare function MessageList({ messages, isStreaming, aiAvatarSrc, size, brandName, userBackgroundColor, }: MessageListProps): import("react/jsx-runtime").JSX.Element;
+export declare function MessageList({ messages, isStreaming, aiAvatarSrc, size, brandName, onChoiceClick, userMessageBackgroundColor, aiColor }: MessageListProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/goji-search/components/elements/search-input.d.ts

@@ -1,5 +1,4 @@
 import type React from "react";
-import type { ReactNode } from "react";
 interface SearchInputProps {
     value: string;
     onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void;
@@ -8,13 +7,18 @@ interface SearchInputProps {
     placeholder: string;
     size: "xs" | "s" | "m" | "l" | "xl";
     setSize: (size: "xs" | "s" | "m" | "l" | "xl") => void;
-    inputRef: React.RefObject<HTMLTextAreaElement>;
+    inputRef: React.RefObject<HTMLTextAreaElement | null>;
     inspirationQuestions: string[];
     onInspirationClick: (question: string) => void;
-    sparkleRef: React.RefObject<HTMLDivElement>;
+    sparkleRef: React.RefObject<HTMLDivElement | null>;
     suggestedLabel?: string;
-    languageSelector?: ReactNode;
+    showLanguageSelector?: boolean;
+    supportedLanguages?: string[];
+    currentLanguage?: string;
+    onLanguageChange?: (lang: string) => void;
+    languageLabels?: Record<string, string>;
+    forceMenuOpenToken?: number;
     color?: string;
 }
-export declare function SearchInput({ value, onChange, onFocus, onBlur, placeholder, size, setSize, inputRef, inspirationQuestions, onInspirationClick, sparkleRef, suggestedLabel, languageSelector, color }: SearchInputProps): import("react/jsx-runtime").JSX.Element;
+export declare function SearchInput({ value, onChange, onFocus, onBlur, placeholder, size, setSize, inputRef, inspirationQuestions, onInspirationClick, sparkleRef, suggestedLabel, showLanguageSelector, supportedLanguages, currentLanguage, onLanguageChange, languageLabels, forceMenuOpenToken, color }: SearchInputProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/goji-search/components/elements/slide-panel.d.ts

@@ -0,0 +1,15 @@
+import type { VisualSlide } from "../../lib/goji-client";
+interface SlidePanelProps {
+    /** Visual slides with id and description */
+    visualSlides: VisualSlide[];
+    isOpen: boolean;
+    onClose: () => void;
+    /** Base URL for slide images (defaults to /slides/) */
+    slidesBasePath?: string;
+    /** Total number of slides (for display like "3/9") - optional */
+    totalSlides?: number;
+    /** Show description below media (default: false). For videos, this could be used for subtitles. */
+    showDescription?: boolean;
+}
+export declare function SlidePanel({ visualSlides, isOpen, onClose, slidesBasePath, totalSlides, showDescription, }: SlidePanelProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/goji-search/components/error-boundary.d.ts

@@ -0,0 +1,16 @@
+import React from "react";
+interface ErrorBoundaryProps {
+    children: React.ReactNode;
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+}
+export declare class GojiSearchErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(_error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    private handleRetry;
+    render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export {};

package/dist/goji-search/components/goji-search-component.d.ts

@@ -16,14 +16,16 @@ export interface GojiSearchComponentProps {
      */
     apiKey: string;
     /**
-     * Initial AI color theme in HEX format
-     * @default "#4654F7"
+     * Custom color for AI avatar animation (CSS color value)
+     * Used by web-component for theming
+     * @example "#4654F7"
      */
     aiColor?: string;
     /**
-     * Background color for user messages in HEX format
-     * @default "#4654F7"
-    */
+     * Custom background color for user message bubbles (CSS color value)
+     * Used by web-component for theming
+     * @example "#E8E8FF"
+     */
     userMessageBackgroundColor?: string;
     /**
      * Widget position on the horizontal axis.

package/dist/goji-search/hooks/useChatStream.d.ts

@@ -0,0 +1,48 @@
+import type { GojiSearchClient, ChatSource, CTACard, EmailRequest, DeepAnalysis, PendingAnalysis, VisualSlide } from "../lib/goji-client";
+import type { VisitorContext } from "../lib/utm-capture";
+export interface Message {
+    role: "user" | "assistant";
+    content: string;
+    timestamp: number;
+    sources?: ChatSource[];
+    slideIds?: number[];
+    isReengagement?: boolean;
+    choices?: string[];
+    choicesSelected?: boolean;
+    choicesVariant?: "default" | "faded" | "dark";
+    choiceMode?: "send" | "action";
+    emailToken?: string;
+}
+export interface UseChatStreamOptions {
+    client: GojiSearchClient;
+    visitorId: string | undefined;
+    companyId: string;
+    supportedLanguages: string[];
+    onLanguageDetected?: (lang: string) => void;
+    onResponseComplete?: () => void;
+    resetIdleTimerRef: React.MutableRefObject<() => void>;
+}
+export interface UseChatStreamReturn {
+    messages: Message[];
+    setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
+    isStreaming: boolean;
+    sessionId: string | undefined;
+    setSessionId: React.Dispatch<React.SetStateAction<string | undefined>>;
+    currentCTACard: CTACard | null;
+    setCurrentCTACard: React.Dispatch<React.SetStateAction<CTACard | null>>;
+    currentEmailRequest: EmailRequest | null;
+    setCurrentEmailRequest: React.Dispatch<React.SetStateAction<EmailRequest | null>>;
+    pendingAnalysis: PendingAnalysis | null;
+    currentAnalysis: DeepAnalysis | null;
+    setCurrentAnalysis: React.Dispatch<React.SetStateAction<DeepAnalysis | null>>;
+    currentVisualSlides: VisualSlide[];
+    isSlidePanelOpen: boolean;
+    setIsSlidePanelOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    backendSuggestedQuestions: string[] | null;
+    setBackendSuggestedQuestions: React.Dispatch<React.SetStateAction<string[] | null>>;
+    streamingCancelRef: React.MutableRefObject<(() => void) | null>;
+    sendMessage: (message: string, language: string, visitorContext: VisitorContext | undefined, options?: {
+        preAction?: () => void;
+    }) => Promise<void>;
+}
+export declare function useChatStream({ client, visitorId, companyId, supportedLanguages, onLanguageDetected, onResponseComplete, resetIdleTimerRef, }: UseChatStreamOptions): UseChatStreamReturn;

package/dist/goji-search/hooks/useCompanyTheme.d.ts

@@ -12,10 +12,37 @@ interface CompanyTheme {
     welcome_message: string;
     placeholder_text: string;
     initial_suggestions: string[];
+    languages?: {
+        supported: string[];
+        default: string;
+    };
+    calendar_link?: string;
+}
+export interface ThemeCSSVars {
+    '--brand-color': string;
+    '--brand-color-dark': string;
+    '--brand-color-light': string;
+    '--brand-color-lighter': string;
+    '--brand-color-rgb': string;
+    '--brand-color-dark-rgb': string;
 }
 export declare function useCompanyTheme(apiUrl: string, companyId: string, apiKey: string): {
     theme: CompanyTheme | null;
+    cssVars: ThemeCSSVars | null;
     loading: boolean;
     error: string | null;
+    applyToElement: (element: HTMLElement | null) => void;
+};
+export declare function parseColor(color: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
 };
+export declare function rgbToHex(r: number, g: number, b: number): string;
+export declare function darken(color: string, amount: number): string;
 export {};

package/dist/goji-search/hooks/useIdleReengagement.d.ts

@@ -0,0 +1,90 @@
+/**
+ * useIdleReengagement Hook
+ *
+ * Manages idle detection and re-engagement prompts for chat visitors.
+ * Detects when a visitor has been idle for a specified time and triggers
+ * a re-engagement request to the backend.
+ */
+export interface IdleReengagementConfig {
+    /** Time in ms before first re-engagement (default: 60000 = 60s) */
+    softTimeoutMs?: number;
+    /** Time in ms before second re-engagement (default: 120000 = 120s) */
+    hardTimeoutMs?: number;
+    /** Minimum time in ms between re-engagement attempts (default: 60000 = 60s) */
+    minBetweenMs?: number;
+    /** Maximum number of re-engagement attempts (default: 2) */
+    maxAttempts?: number;
+}
+export interface IdleReengagementState {
+    /** Number of re-engagement attempts made this session */
+    attemptCount: number;
+    /** Whether re-engagement is currently blocked */
+    isBlocked: boolean;
+    /** Reason for blocking (if any) */
+    blockedReason: string | null;
+    /** Time until next re-engagement check (ms) */
+    timeUntilNextCheck: number | null;
+    /** Whether the idle timer is active */
+    isTimerActive: boolean;
+}
+export interface UseIdleReengagementOptions {
+    /** Configuration for timeouts and limits */
+    config?: IdleReengagementConfig;
+    /** Whether the widget is minimized (blocks re-engagement) */
+    isMinimized?: boolean;
+    /** Whether the assistant is currently streaming a response */
+    isStreaming?: boolean;
+    /** Whether a CTA card is currently displayed */
+    hasCTACard?: boolean;
+    /** Whether an email request is currently displayed */
+    hasEmailRequest?: boolean;
+    /** Whether the calendar is open */
+    isCalendarOpen?: boolean;
+    /** Whether there are any messages in the conversation */
+    hasMessages?: boolean;
+    /** Current session ID (required for re-engagement) */
+    sessionId?: string;
+    /** Callback when re-engagement should be triggered */
+    onReengagementTrigger?: (attempt: number) => void;
+    /** Whether idle detection should be enabled */
+    enabled?: boolean;
+}
+export interface UseIdleReengagementResult {
+    /** Current state of the re-engagement system */
+    state: IdleReengagementState;
+    /** Reset the idle timer (call on user activity) */
+    resetTimer: () => void;
+    /** Stop the idle timer completely */
+    stopTimer: () => void;
+    /** Start or restart the idle timer */
+    startTimer: () => void;
+    /** Increment attempt count (call after re-engagement sent) */
+    incrementAttempt: () => void;
+    /** Reset the entire re-engagement state for a new session */
+    resetState: () => void;
+}
+/**
+ * Hook for managing idle detection and re-engagement prompts.
+ *
+ * Tracks visitor idle time and triggers re-engagement when thresholds are met.
+ * Respects blocking conditions (CTA displayed, streaming, minimized, etc.)
+ *
+ * @example
+ * ```tsx
+ * const { state, resetTimer, incrementAttempt } = useIdleReengagement({
+ *   isMinimized: size === "xs",
+ *   isStreaming,
+ *   hasCTACard: !!currentCTACard,
+ *   hasMessages: messages.length > 0,
+ *   sessionId,
+ *   onReengagementTrigger: (attempt) => {
+ *     // Request re-engagement from backend
+ *     client.requestReengagement(sessionId, attempt)
+ *   },
+ * })
+ *
+ * // Reset timer on user activity
+ * const handleUserActivity = () => resetTimer()
+ * ```
+ */
+export declare function useIdleReengagement(options: UseIdleReengagementOptions): UseIdleReengagementResult;

package/dist/goji-search/hooks/useReturningVisitor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * useReturningVisitor Hook
+ *
+ * Manages returning visitor detection and personalized welcome messages.
+ * Checks if the visitor has been here before and loads their context.
+ */
+import type { GojiSearchClient, ReturningVisitorContext } from "../lib/goji-client";
+export interface UseReturningVisitorResult {
+    /** Whether the visitor has been here before */
+    isReturning: boolean;
+    /** Whether we're still loading the visitor context */
+    isLoading: boolean;
+    /** The visitor's unique ID */
+    visitorId: string;
+    /** Full visitor context (if returning) */
+    visitorContext: ReturningVisitorContext | null;
+    /** Personalized or default welcome message */
+    welcomeMessage: string | null;
+    /** Visitor's preferred language (if returning) */
+    preferredLanguage: string | null;
+    /** Error if context loading failed */
+    error: Error | null;
+    /** Manually refresh the visitor context */
+    refresh: () => Promise<void>;
+}
+export interface UseReturningVisitorOptions {
+    /** The GojiSearch client instance */
+    client: GojiSearchClient;
+    /** Default language for welcome message */
+    language?: string;
+    /** Whether to automatically fetch context on mount */
+    autoFetch?: boolean;
+    /** Callback when returning visitor is detected */
+    onReturningVisitor?: (context: ReturningVisitorContext) => void;
+}
+/**
+ * Hook for managing returning visitor detection and personalization.
+ *
+ * On mount:
+ * 1. Gets or creates a visitor ID (stored in localStorage)
+ * 2. Checks if visitor is returning via backend API
+ * 3. Returns their context and personalized welcome message
+ *
+ * @example
+ * ```tsx
+ * const { isReturning, welcomeMessage, visitorId } = useReturningVisitor({
+ *   client,
+ *   language: "en",
+ * })
+ *
+ * // Use welcomeMessage instead of default welcome for returning visitors
+ * const displayMessage = isReturning ? welcomeMessage : defaultWelcome
+ * ```
+ */
+export declare function useReturningVisitor(options: UseReturningVisitorOptions): UseReturningVisitorResult;
+/**
+ * Lightweight hook that just provides the visitor ID without fetching context.
+ *
+ * Use this when you only need the visitor ID for tracking purposes.
+ */
+export declare function useVisitorId(): string;

package/dist/goji-search/lib/debug.d.ts

@@ -0,0 +1,9 @@
+declare global {
+    interface Window {
+        __GOJI_DEBUG__?: boolean;
+    }
+}
+export declare function isGojiDebugEnabled(): boolean;
+export declare function gojiDebugLog(...args: unknown[]): void;
+export declare function gojiDebugWarn(...args: unknown[]): void;
+export declare function gojiDebugError(...args: unknown[]): void;