@agentman/chat-widget/dist/assistantWidget/types/events.d.ts

Agentman Chat Widget for easy integration with web applications

import type { Message, ChatState, ChatTheme } from './types';
/**
 * Event Schema for ChatWidget Event-Driven Architecture
 *
 * This file defines all events that can be emitted and consumed
 * within the ChatWidget ecosystem for loose coupling between components.
 */
export interface BaseEvent {
    timestamp: number;
    source?: string;
}
export interface UserInputEvent extends BaseEvent {
    message: string;
    source: 'welcome' | 'conversation';
    isFirstMessage?: boolean;
}
export interface PromptClickEvent extends BaseEvent {
    prompt: string;
    source: 'welcome' | 'conversation';
    isFirstMessage?: boolean;
}
export interface ToggleEvent extends BaseEvent {
    isOpen: boolean;
}
export interface ExpandEvent extends BaseEvent {
    isExpanded: boolean;
}
export interface MessageSentEvent extends BaseEvent {
    message: Message;
    isFirstMessage: boolean;
}
export interface MessageReceivedEvent extends BaseEvent {
    messages: Message[];
    totalCount: number;
}
export interface MessageErrorEvent extends BaseEvent {
    error: Error;
    userMessage?: string;
}
export interface ApiRequestEvent extends BaseEvent {
    endpoint: string;
    method: string;
    params: any;
}
export interface ApiResponseEvent extends BaseEvent {
    endpoint: string;
    success: boolean;
    data?: any;
    error?: Error;
}
export interface ApiErrorEvent extends BaseEvent {
    endpoint: string;
    error: Error;
    retry?: boolean;
}
export interface ViewTransitionEvent extends BaseEvent {
    from: 'welcome' | 'conversation';
    to: 'welcome' | 'conversation';
    reason: 'user_input' | 'prompt_click' | 'new_conversation' | 'reset';
}
export interface ViewChangedEvent extends BaseEvent {
    currentView: 'welcome' | 'conversation';
    previousView?: 'welcome' | 'conversation';
}
export interface StateChangedEvent extends BaseEvent {
    state: ChatState;
    changes: Partial<ChatState>;
}
export interface ThemeChangedEvent extends BaseEvent {
    theme: Partial<ChatTheme>;
}
export interface LoadingStartedEvent extends BaseEvent {
    operation: 'message_send' | 'agent_init' | 'file_upload' | 'conversation_load';
    message?: string;
}
export interface LoadingEndedEvent extends BaseEvent {
    operation: 'message_send' | 'agent_init' | 'file_upload' | 'conversation_load';
    success: boolean;
    duration: number;
}
export interface LoadingTimeoutEvent extends BaseEvent {
    operationId: string;
    operation: string;
    allowedToContinue: boolean;
}
export interface LoadingStateChangedEvent extends BaseEvent {
    previousState: 'none' | 'initial' | 'streaming';
    currentState: 'none' | 'initial' | 'streaming';
}
export interface LoadingHideInitialEvent extends BaseEvent {
    reason: string;
}
export interface LoadingCompleteEvent extends BaseEvent {
    previousState: 'none' | 'initial' | 'streaming';
}
export interface FileSelectedEvent extends BaseEvent {
    files: FileList;
}
export interface FileUploadStartedEvent extends BaseEvent {
    file: File;
    fileId: string;
}
export interface FileUploadProgressEvent extends BaseEvent {
    fileId: string;
    progress: number;
}
export interface FileUploadCompletedEvent extends BaseEvent {
    fileId: string;
    success: boolean;
    error?: string;
}
export interface AttachmentRemovedEvent extends BaseEvent {
    fileId: string;
}
export interface FileUploadCancelledEvent extends BaseEvent {
    fileId: string;
}
export interface AgentInitializedEvent extends BaseEvent {
    capabilities: any;
    metadata: any;
}
export interface AgentCapabilitiesUpdatedEvent extends BaseEvent {
    capabilities: any;
}
export interface ErrorOccurredEvent extends BaseEvent {
    error: Error;
    context: string;
    severity: 'low' | 'medium' | 'high' | 'critical';
    userVisible: boolean;
}
export interface ErrorResolvedEvent extends BaseEvent {
    error: Error;
    resolution: string;
}
export interface ConversationSavedEvent extends BaseEvent {
    conversationId: string;
    messageCount: number;
}
export interface ConversationLoadedEvent extends BaseEvent {
    conversationId: string;
    messages: Message[];
}
export interface ConversationClearedEvent extends BaseEvent {
    conversationId: string;
}
export interface WidgetInitializedEvent extends BaseEvent {
    config: any;
    variant: string;
}
export interface WidgetDestroyedEvent extends BaseEvent {
    reason: 'user_action' | 'page_unload' | 'error' | 'programmatic';
}
export interface WidgetResizedEvent extends BaseEvent {
    width: number;
    height: number;
    isMobile: boolean;
}
export interface DebugEvent extends BaseEvent {
    level: 'debug' | 'info' | 'warn' | 'error';
    message: string;
    data?: any;
}
/**
 * Event Type Registry - Maps event names to their data types
 */
export interface EventTypeRegistry {
    'user:input': UserInputEvent;
    'user:prompt_click': PromptClickEvent;
    'user:toggle': ToggleEvent;
    'user:expand': ExpandEvent;
    'message:sent': MessageSentEvent;
    'message:received': MessageReceivedEvent;
    'message:error': MessageErrorEvent;
    'api:request': ApiRequestEvent;
    'api:response': ApiResponseEvent;
    'api:error': ApiErrorEvent;
    'view:transition_start': ViewTransitionEvent;
    'view:transition_end': ViewTransitionEvent;
    'view:changed': ViewChangedEvent;
    'state:changed': StateChangedEvent;
    'theme:changed': ThemeChangedEvent;
    'loading:start': LoadingStartedEvent;
    'loading:end': LoadingEndedEvent;
    'loading:timeout': LoadingTimeoutEvent;
    'loading:stateChanged': LoadingStateChangedEvent;
    'loading:hideInitial': LoadingHideInitialEvent;
    'loading:complete': LoadingCompleteEvent;
    'file:selected': FileSelectedEvent;
    'file:upload_start': FileUploadStartedEvent;
    'file:upload_progress': FileUploadProgressEvent;
    'file:upload_complete': FileUploadCompletedEvent;
    'file:attachment_removed': AttachmentRemovedEvent;
    'file:upload_cancelled': FileUploadCancelledEvent;
    'agent:initialized': AgentInitializedEvent;
    'agent:capabilities_updated': AgentCapabilitiesUpdatedEvent;
    'error:occurred': ErrorOccurredEvent;
    'error:resolved': ErrorResolvedEvent;
    'validation:error': ErrorOccurredEvent;
    'file:error': ErrorOccurredEvent;
    'config:error': ErrorOccurredEvent;
    'storage:error': ErrorOccurredEvent;
    'error:logged': ErrorOccurredEvent;
    'error:unknown': ErrorOccurredEvent;
    'conversation:saved': ConversationSavedEvent;
    'conversation:loaded': ConversationLoadedEvent;
    'conversation:cleared': ConversationClearedEvent;
    'conversation:started': {
        conversationId: string;
        hasInitialMessage: boolean;
        source: string;
        timestamp: number;
    };
    'conversation:message_sent': {
        conversationId: string;
        messageCount: number;
        hasAttachments: boolean;
        source: string;
        timestamp: number;
    };
    'conversation:error': {
        conversationId: string;
        error: Error;
        operation: string;
        source: string;
        timestamp: number;
    };
    'conversation:deleted': {
        conversationId: string;
        source: string;
        timestamp: number;
    };
    'conversation:switch_requested': {
        conversationId: string;
        source: string;
        timestamp: number;
    };
    'conversation:delete_requested': {
        conversationId: string;
        source: string;
        timestamp: number;
    };
    'conversation:new_requested': {
        source: string;
        timestamp: number;
    };
    'widget:initialized': WidgetInitializedEvent;
    'widget:destroyed': WidgetDestroyedEvent;
    'widget:resized': WidgetResizedEvent;
    'debug:log': DebugEvent;
}
/**
 * Type helper for event emission
 */
export type EventName = keyof EventTypeRegistry;
export type EventData<T extends EventName> = EventTypeRegistry[T];
/**
 * Helper to create typed events
 */
export declare function createEvent<T extends EventName>(type: T, data: Omit<EventData<T>, 'timestamp'> & {
    source?: string;
}): EventData<T>;
/**
 * Event priority levels for ordering
 */
export declare enum EventPriority {
    LOW = 0,
    NORMAL = 1,
    HIGH = 2,
    CRITICAL = 3
}
/**
 * Event categories for filtering and debugging
 */
export declare enum EventCategory {
    USER_INTERACTION = "user_interaction",
    MESSAGE_LIFECYCLE = "message_lifecycle",
    API_COMMUNICATION = "api_communication",
    VIEW_MANAGEMENT = "view_management",
    STATE_MANAGEMENT = "state_management",
    FILE_HANDLING = "file_handling",
    AGENT_MANAGEMENT = "agent_management",
    ERROR_HANDLING = "error_handling",
    PERSISTENCE = "persistence",
    WIDGET_LIFECYCLE = "widget_lifecycle",
    DEBUG = "debug"
}
/**
 * Event metadata for enhanced debugging and monitoring
 */
export interface EventMetadata {
    category: EventCategory;
    priority: EventPriority;
    description: string;
    examples?: string[];
}
/**
 * Registry of event metadata for documentation and tooling
 */
export declare const EVENT_METADATA: Record<EventName, EventMetadata>;