@hissuno/widget 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,507 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, FormEvent } from 'react';
+import { Message } from '@ai-sdk/react';
+export { Message } from '@ai-sdk/react';
+
+/**
+ * Position options for the bubble trigger
+ */
+type BubblePosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/**
+ * Widget trigger types - what activates the widget
+ */
+type WidgetTrigger = 'bubble' | 'drawer-badge' | 'headless';
+/**
+ * Widget display types - how the chat UI appears
+ */
+type WidgetDisplay = 'popup' | 'sidepanel' | 'dialog';
+/**
+ * Offset configuration for bubble positioning
+ */
+interface BubbleOffset {
+    x?: number;
+    y?: number;
+}
+/**
+ * Props passed to the custom trigger render function
+ */
+interface TriggerRenderProps {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    isOpen: boolean;
+}
+/**
+ * Props for the HissunoWidget component
+ */
+interface HissunoWidgetProps {
+    /**
+     * The project ID from your Hissuno dashboard
+     * This uniquely identifies your project
+     */
+    projectId: string;
+    /**
+     * JWT token for secure widget authentication (optional)
+     * Generated on your backend using your project's secret key
+     * Required if widget_token_required is enabled on the project
+     */
+    widgetToken?: string;
+    /**
+     * Widget trigger type - what activates the widget
+     * - 'bubble': Floating 56x56 button at configurable corner position
+     * - 'drawer-badge': Vertical tab fixed to right edge with rotated label
+     * - 'headless': No visual element, keyboard-only activation
+     * @default "bubble"
+     */
+    trigger?: WidgetTrigger;
+    /**
+     * Widget display type - how the chat UI appears
+     * - 'popup': Corner modal (380x520px)
+     * - 'sidepanel': Full-height right drawer (400px)
+     * - 'dialog': Centered modal with blur backdrop
+     * @default "sidepanel"
+     */
+    display?: WidgetDisplay;
+    /**
+     * Keyboard shortcut to open/toggle the widget
+     * Supports 'mod+k' (cmd on Mac, ctrl on Windows/Linux), 'ctrl+shift+p', etc.
+     * Set to false to disable keyboard activation
+     * @default "mod+k"
+     */
+    shortcut?: string | false;
+    /**
+     * Whether to fetch default settings from the server
+     * When true, the widget will fetch settings using the publicKey and use them as defaults.
+     * Explicit props will always override fetched defaults.
+     * @default true
+     */
+    fetchDefaults?: boolean;
+    /**
+     * Optional identifier for the end-user using the widget
+     * This helps track sessions per user in your Hissuno dashboard
+     */
+    userId?: string;
+    /**
+     * Optional metadata about the end-user (e.g., name, email, plan)
+     * This information will be visible in session details
+     */
+    userMetadata?: Record<string, string>;
+    /**
+     * The URL of your Hissuno API endpoint
+     * @default "/api/agent"
+     */
+    apiUrl?: string;
+    /**
+     * Theme for the chat widget
+     * @default "light"
+     */
+    theme?: 'light' | 'dark' | 'auto';
+    /**
+     * Position of the floating bubble on the page
+     * Only applies when trigger='bubble'
+     * @default "bottom-right"
+     */
+    bubblePosition?: BubblePosition;
+    /**
+     * Offset from the edge of the screen in pixels
+     * Only applies when trigger='bubble'
+     * @default { x: 20, y: 20 }
+     */
+    bubbleOffset?: BubbleOffset;
+    /**
+     * Label text for the drawer badge trigger
+     * Only applies when trigger='drawer-badge'
+     * @default "Support"
+     */
+    drawerBadgeLabel?: string;
+    /**
+     * Width of the dialog display
+     * Only applies when display='dialog'
+     * @default 600
+     */
+    dialogWidth?: number;
+    /**
+     * Height of the dialog display
+     * Only applies when display='dialog'
+     * @default 500
+     */
+    dialogHeight?: number;
+    /**
+     * Custom render function for the trigger element
+     * Use this to provide your own button/component to open the chat
+     */
+    renderTrigger?: (props: TriggerRenderProps) => ReactNode;
+    /**
+     * Custom title for the chat window
+     * @default "Support"
+     */
+    title?: string;
+    /**
+     * Custom placeholder text for the input field
+     * @default "Ask a question or report an issue..."
+     */
+    placeholder?: string;
+    /**
+     * Initial message shown when the chat opens
+     * @default "Hi! How can I help you today?"
+     */
+    initialMessage?: string;
+    /**
+     * Whether the chat window should be open by default
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Callback when the chat window opens
+     */
+    onOpen?: () => void;
+    /**
+     * Callback when the chat window closes
+     */
+    onClose?: () => void;
+    /**
+     * Additional CSS class name for custom styling
+     */
+    className?: string;
+    /**
+     * Custom headers to send with each request
+     */
+    headers?: Record<string, string>;
+}
+/**
+ * Configuration for the Hissuno widget
+ */
+interface HissunoConfig {
+    projectId: string;
+    apiUrl: string;
+    widgetToken?: string;
+}
+/**
+ * Sender type for messages
+ */
+type MessageSenderType = 'ai' | 'human_agent' | 'system';
+/**
+ * Chat message structure
+ */
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    createdAt?: Date;
+    senderType?: MessageSenderType;
+}
+/**
+ * Widget settings fetched from server
+ */
+interface WidgetSettings {
+    trigger: WidgetTrigger;
+    display: WidgetDisplay;
+    shortcut: string | false;
+    theme: 'light' | 'dark' | 'auto';
+    position: BubblePosition;
+    title: string;
+    initialMessage: string;
+    drawerBadgeLabel?: string;
+    tokenRequired?: boolean;
+    blocked?: boolean;
+}
+
+/**
+ * HissunoWidget - Embeddable support agent widget
+ *
+ * Add this component to your app to enable AI-powered support.
+ *
+ * @example
+ * ```tsx
+ * import { HissunoWidget } from '@hissuno/widget';
+ * import '@hissuno/widget/styles.css';
+ *
+ * function App() {
+ *   return (
+ *     <div>
+ *       <YourApp />
+ *       <HissunoWidget
+ *         projectId="your-project-id"
+ *         widgetToken={generatedToken} // Optional: generated on your backend
+ *         userId={currentUser.id}
+ *         userMetadata={{ name: currentUser.name, email: currentUser.email }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function HissunoWidget({ projectId, widgetToken, trigger: propTrigger, display: propDisplay, shortcut: propShortcut, fetchDefaults, userId, userMetadata, apiUrl, theme: propTheme, bubblePosition: propBubblePosition, bubbleOffset, drawerBadgeLabel: propDrawerBadgeLabel, dialogWidth: propDialogWidth, dialogHeight: propDialogHeight, renderTrigger, title: propTitle, placeholder, initialMessage: propInitialMessage, defaultOpen, onOpen, onClose, className, headers, }: HissunoWidgetProps): react_jsx_runtime.JSX.Element | null;
+
+interface ChatBubbleProps {
+    isOpen: boolean;
+    onClick: () => void;
+    position?: BubblePosition;
+    offset?: BubbleOffset;
+    theme?: 'light' | 'dark';
+}
+declare function ChatBubble({ isOpen, onClick, position, offset, theme, }: ChatBubbleProps): react_jsx_runtime.JSX.Element;
+
+interface DrawerBadgeProps {
+    isOpen: boolean;
+    onClick: () => void;
+    label?: string;
+    theme?: 'light' | 'dark';
+}
+declare function DrawerBadge({ isOpen, onClick, label, theme, }: DrawerBadgeProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Session entry for conversation history
+ * Stored in localStorage when userId is provided
+ */
+interface SessionEntry {
+    /** Unique session identifier */
+    sessionId: string;
+    /** User who owns this session */
+    userId: string;
+    /** Title derived from first user message */
+    title: string;
+    /** ISO timestamp of last message */
+    lastMessageAt: string;
+    /** Total number of messages in session */
+    messageCount: number;
+}
+/**
+ * Options for the useHissunoChat hook
+ */
+interface UseHissunoChatOptions {
+    /** Required: Your Hissuno project ID */
+    projectId: string;
+    /** JWT token for secure widget authentication */
+    widgetToken?: string;
+    /** Custom API endpoint URL (default: '/api/agent') */
+    apiUrl?: string;
+    /** Initial assistant message shown when chat opens */
+    initialMessage?: string;
+    /** Custom headers to include with API requests */
+    headers?: Record<string, string>;
+    /** End-user identifier for session tracking and history */
+    userId?: string;
+    /** Additional user metadata (name, email, plan, etc.) */
+    userMetadata?: Record<string, string>;
+    /** Custom session ID (auto-generated if not provided) */
+    sessionId?: string;
+    /** Inactivity timeout in ms before auto-closing session (default: 30 minutes) */
+    inactivityTimeout?: number;
+    /** Callback when session is closed */
+    onSessionClose?: () => void;
+}
+/**
+ * Return type for the useHissunoChat hook
+ */
+interface UseHissunoChatReturn {
+    /** All chat messages in the current session */
+    messages: ChatMessage[];
+    /** Current input field value */
+    input: string;
+    /** Update the input field value */
+    setInput: (value: string) => void;
+    /** Submit the current message */
+    handleSubmit: (e?: React.FormEvent) => void;
+    /** Whether waiting for a response */
+    isLoading: boolean;
+    /** Whether response is currently streaming */
+    isStreaming: boolean;
+    /** Partial content being streamed */
+    streamingContent: string;
+    /** Last error that occurred */
+    error: Error | undefined;
+    /** Clear history and start a new conversation */
+    clearHistory: () => void;
+    /** Current session ID */
+    currentSessionId: string | null;
+    /** Load a previous session by ID */
+    loadSession: (sessionId: string, sessionMessages?: Message[]) => void;
+    /** Close current session and trigger PM review */
+    closeSession: () => Promise<void>;
+    /** Cancel an in-progress streaming response */
+    cancelChat: () => Promise<void>;
+    /** Get list of past sessions (requires userId) */
+    getSessionHistory: () => SessionEntry[];
+    /** Delete a session from history (requires userId) */
+    deleteSession: (sessionId: string) => void;
+}
+/**
+ * React hook for managing Hissuno chat functionality
+ *
+ * Provides complete chat state management including messages, input handling,
+ * streaming responses, session management, and conversation history.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   messages,
+ *   input,
+ *   setInput,
+ *   handleSubmit,
+ *   isLoading,
+ *   isStreaming,
+ *   streamingContent,
+ * } = useHissunoChat({
+ *   projectId: 'your-project-id',
+ *   userId: 'user-123',
+ * });
+ * ```
+ *
+ * @param options - Hook configuration options
+ * @returns Chat state and control functions
+ */
+declare function useHissunoChat({ projectId, widgetToken, apiUrl, initialMessage, headers, userId, userMetadata, sessionId: providedSessionId, inactivityTimeout, onSessionClose, }: UseHissunoChatOptions): UseHissunoChatReturn;
+
+interface ChatPopupProps {
+    isOpen: boolean;
+    onClose: () => void;
+    messages: ChatMessage[];
+    input: string;
+    setInput: (value: string) => void;
+    handleSubmit: (e?: FormEvent) => void;
+    isLoading: boolean;
+    isStreaming?: boolean;
+    streamingContent?: string;
+    error?: Error;
+    title?: string;
+    placeholder?: string;
+    theme?: 'light' | 'dark';
+    position?: BubblePosition;
+    offset?: BubbleOffset;
+    onClearHistory?: () => void;
+    onCancelChat?: () => void;
+    onOpenHistory?: () => void;
+    isHistoryOpen?: boolean;
+    sessionHistory?: SessionEntry[];
+    currentSessionId?: string | null;
+    onCloseHistory?: () => void;
+    onSelectSession?: (sessionId: string) => void;
+    onDeleteSession?: (sessionId: string) => void;
+}
+declare function ChatPopup({ isOpen, onClose, messages, input, setInput, handleSubmit, isLoading, isStreaming, streamingContent, error, title, placeholder, theme, position, offset, onClearHistory, onCancelChat, onOpenHistory, isHistoryOpen, sessionHistory, currentSessionId, onCloseHistory, onSelectSession, onDeleteSession, }: ChatPopupProps): react_jsx_runtime.JSX.Element | null;
+
+interface ChatSidepanelProps {
+    isOpen: boolean;
+    onClose: () => void;
+    messages: ChatMessage[];
+    input: string;
+    setInput: (value: string) => void;
+    handleSubmit: (e?: FormEvent) => void;
+    isLoading: boolean;
+    isStreaming?: boolean;
+    streamingContent?: string;
+    error?: Error;
+    title?: string;
+    placeholder?: string;
+    theme?: 'light' | 'dark';
+    onClearHistory?: () => void;
+    onCancelChat?: () => void;
+    onOpenHistory?: () => void;
+    isHistoryOpen?: boolean;
+    sessionHistory?: SessionEntry[];
+    currentSessionId?: string | null;
+    onCloseHistory?: () => void;
+    onSelectSession?: (sessionId: string) => void;
+    onDeleteSession?: (sessionId: string) => void;
+}
+declare function ChatSidepanel({ isOpen, onClose, messages, input, setInput, handleSubmit, isLoading, isStreaming, streamingContent, error, title, placeholder, theme, onClearHistory, onCancelChat, onOpenHistory, isHistoryOpen, sessionHistory, currentSessionId, onCloseHistory, onSelectSession, onDeleteSession, }: ChatSidepanelProps): react_jsx_runtime.JSX.Element | null;
+
+interface ChatDialogProps {
+    isOpen: boolean;
+    onClose: () => void;
+    messages: ChatMessage[];
+    input: string;
+    setInput: (value: string) => void;
+    handleSubmit: (e?: FormEvent) => void;
+    isLoading: boolean;
+    isStreaming?: boolean;
+    streamingContent?: string;
+    error?: Error;
+    title?: string;
+    placeholder?: string;
+    theme?: 'light' | 'dark';
+    width?: number;
+    height?: number;
+    onClearHistory?: () => void;
+    onCancelChat?: () => void;
+    onOpenHistory?: () => void;
+    isHistoryOpen?: boolean;
+    sessionHistory?: SessionEntry[];
+    currentSessionId?: string | null;
+    onCloseHistory?: () => void;
+    onSelectSession?: (sessionId: string) => void;
+    onDeleteSession?: (sessionId: string) => void;
+}
+declare function ChatDialog({ isOpen, onClose, messages, input, setInput, handleSubmit, isLoading, isStreaming, streamingContent, error, title, placeholder, theme, width, height, onClearHistory, onCancelChat, onOpenHistory, isHistoryOpen, sessionHistory, currentSessionId, onCloseHistory, onSelectSession, onDeleteSession, }: ChatDialogProps): react_jsx_runtime.JSX.Element | null;
+
+interface ChatMessagesProps {
+    messages: ChatMessage[];
+    isLoading: boolean;
+    isStreaming?: boolean;
+    streamingContent?: string;
+    theme?: 'light' | 'dark';
+}
+declare function ChatMessages({ messages, isLoading, isStreaming, streamingContent, theme, }: ChatMessagesProps): react_jsx_runtime.JSX.Element;
+
+interface ConversationHistoryProps {
+    isOpen: boolean;
+    onClose: () => void;
+    sessions: SessionEntry[];
+    onSelectSession: (sessionId: string) => void;
+    onDeleteSession: (sessionId: string) => void;
+    currentSessionId?: string | null;
+    theme?: 'light' | 'dark';
+}
+declare function ConversationHistory({ isOpen, onClose, sessions, onSelectSession, onDeleteSession, currentSessionId, theme, }: ConversationHistoryProps): react_jsx_runtime.JSX.Element;
+
+declare function HistoryIcon(): react_jsx_runtime.JSX.Element;
+
+interface UseKeyboardShortcutOptions {
+    /**
+     * Shortcut string (e.g., 'mod+k', 'ctrl+shift+p')
+     * Set to false or undefined to disable
+     */
+    shortcut?: string | false;
+    /**
+     * Callback when shortcut is triggered
+     */
+    onTrigger: () => void;
+    /**
+     * Whether the shortcut is enabled
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Hook to register a keyboard shortcut
+ *
+ * @example
+ * useKeyboardShortcut({
+ *   shortcut: 'mod+k',
+ *   onTrigger: () => setIsOpen(true),
+ * });
+ */
+declare function useKeyboardShortcut({ shortcut, onTrigger, enabled, }: UseKeyboardShortcutOptions): void;
+/**
+ * Format a shortcut string for display
+ * Converts 'mod+k' to 'Cmd+K' on Mac or 'Ctrl+K' on Windows
+ */
+declare function formatShortcut(shortcut: string): string;
+
+/**
+ * Hook to resolve 'auto' theme to 'light' or 'dark' based on system preference
+ */
+declare function useResolvedTheme(theme: 'light' | 'dark' | 'auto'): 'light' | 'dark';
+
+/**
+ * Hook to trap focus within a container element
+ * Used for modal dialogs to maintain accessibility compliance
+ *
+ * @param isActive - Whether the focus trap should be active
+ * @returns Ref to attach to the container element
+ */
+declare function useFocusTrap<T extends HTMLElement = HTMLElement>(isActive: boolean): react.RefObject<T | null>;
+
+export { type BubbleOffset, type BubblePosition, ChatBubble, ChatDialog, type ChatMessage, ChatMessages, ChatPopup, ChatSidepanel, ConversationHistory, DrawerBadge, type HissunoConfig, HissunoWidget, type HissunoWidgetProps, HistoryIcon, type SessionEntry, HissunoWidget as SupportWidget, type TriggerRenderProps, type UseHissunoChatOptions, type UseHissunoChatReturn, type WidgetDisplay, type WidgetSettings, type WidgetTrigger, formatShortcut, useFocusTrap, useHissunoChat, useKeyboardShortcut, useResolvedTheme };