@enjoys/react-chatbot-plugin 1.3.0 → 1.5.0

package/dist/index.d.ts

@@ -12,14 +12,64 @@ export declare interface ActionContext {
 }
 
 /**
- * Analytics Plugin — tracks message counts, form completions, drop-offs
+ * Agent Plugin — enables live human agent takeover of the chat
+ */
+export declare function agentPlugin(options: {
+    socketUrl?: string;
+    onAgentConnect?: (ctx: PluginContext) => void;
+    onAgentDisconnect?: (ctx: PluginContext) => void;
+    onAgentMessage?: (text: string, ctx: PluginContext) => void;
+    connectMessage?: string;
+    disconnectMessage?: string;
+}): ChatPlugin;
+
+/**
+ * AI Plugin — generates bot responses using external AI providers (OpenAI, Anthropic, custom)
+ */
+export declare function aiPlugin(options: {
+    provider?: 'openai' | 'anthropic' | 'custom';
+    endpoint?: string;
+    apiKey?: string;
+    model?: string;
+    systemPrompt?: string;
+    headers?: Record<string, string>;
+    shouldRespond?: (text: string) => boolean;
+    parseResponse?: (response: unknown) => string;
+    timeout?: number;
+}): ChatPlugin;
+
+/**
+ * Analytics Plugin — tracks sessions, messages, forms, timing, and step progression
  */
 export declare function analyticsPlugin(options?: {
     onTrack?: (event: string, data?: unknown) => void;
+    sessionId?: string;
 }): ChatPlugin;
 
 export declare const AttachmentIcon: default_2.FC<IconProps>;
 
+/**
+ * Auth Plugin — manages user authentication and identity
+ */
+export declare function authPlugin(options: {
+    type?: 'jwt' | 'session' | 'custom';
+    tokenKey?: string;
+    storage?: 'local' | 'session';
+    onAuth?: (token: string, ctx: PluginContext) => void;
+    onAuthExpired?: (ctx: PluginContext) => void;
+    validateToken?: (token: string) => boolean;
+}): ChatPlugin;
+
+/**
+ * Auto Reply Plugin — sends automated replies when user is inactive
+ */
+export declare function autoReplyPlugin(options?: {
+    timeout?: number;
+    message?: string;
+    maxReplies?: number;
+    onlyWhenOpen?: boolean;
+}): ChatPlugin;
+
 export declare const Branding: default_2.FC<BrandingProps>;
 
 export declare interface BrandingConfig {
@@ -4376,6 +4426,22 @@ export declare function buildStyles(theme: Required<ChatTheme>, overrides?: Chat
     };
 };
 
+declare interface CampaignConfig {
+    trigger: TriggerType;
+    message: string;
+    delay?: number;
+    maxShows?: number;
+    flowStep?: string;
+}
+
+/**
+ * Campaign Plugin — starts flows or shows messages based on user behavior triggers
+ */
+export declare function campaignPlugin(options: {
+    campaigns: CampaignConfig[];
+    onTrigger?: (campaign: CampaignConfig, ctx: PluginContext) => void;
+}): ChatPlugin;
+
 declare type ChatAction = {
     type: 'TOGGLE_OPEN';
 } | {
@@ -4448,6 +4514,14 @@ export declare interface ChatBotProps {
     actionHandlers?: Record<string, (data: Record<string, unknown>, ctx: ActionContext) => Promise<FlowActionResult>>;
     /** Override built-in form field renderers per field type. Each renderer receives strongly-typed props + the default element. */
     renderFormField?: FormFieldRenderMap;
+    /** Fallback message when user types text with no active flow or unmatched input */
+    fallbackMessage?: string | ((text: string) => string | null);
+    /** Keyword routes — match user text to responses or flow steps */
+    keywords?: KeywordRoute[];
+    /** Convenience: auto-respond to common greetings (hello, hi, hey, etc.) */
+    greetingResponse?: string;
+    /** Typing delay in ms before bot sends keyword/fallback replies (default: 0) */
+    typingDelay?: number;
 }
 
 export declare const ChatBubbleIcon: default_2.FC<IconProps>;
@@ -4465,6 +4539,10 @@ export declare interface ChatCallbacks {
     onFlowEnd?: (collectedData: Record<string, unknown>) => void;
     onError?: (error: Error) => void;
     onEvent?: (event: string, payload?: unknown) => void;
+    /** Called when user types text the bot couldn't handle */
+    onUnhandledMessage?: (text: string, context: {
+        currentStepId: string | null;
+    }) => void;
 }
 
 export declare const ChatContext: Context<ChatContextValue | null>;
@@ -4473,6 +4551,7 @@ declare interface ChatContextValue {
     state: ChatState;
     dispatch: React.Dispatch<ChatAction>;
     props: ChatBotProps;
+    pluginManager?: PluginManager | null;
 }
 
 export declare const ChatHeader: default_2.FC<ChatHeaderProps>;
@@ -4617,6 +4696,54 @@ export declare interface CheckboxFieldRenderProps {
 
 export declare const CloseIcon: default_2.FC<IconProps>;
 
+/**
+ * Component Plugin — injects custom component messages into chat via events
+ */
+export declare function componentPlugin(options?: {
+    components?: Record<string, string>;
+    onRender?: (componentKey: string, ctx: PluginContext) => void;
+}): ChatPlugin;
+
+/**
+ * CRM Plugin — pushes user/lead data to CRM systems
+ */
+export declare function crmPlugin(options: {
+    endpoint: string;
+    provider?: string;
+    headers?: Record<string, string>;
+    mapFields?: (data: Record<string, unknown>) => Record<string, unknown>;
+    events?: ('submit' | 'flowEnd' | 'login')[];
+}): ChatPlugin;
+
+/**
+ * Debug Plugin — exposes internal state and flow progression for debugging
+ */
+export declare function debugPlugin(options?: {
+    logState?: boolean;
+    logEvents?: boolean;
+    logMessages?: boolean;
+    groupName?: string;
+}): ChatPlugin;
+
+/**
+ * DevTools Plugin — provides a visual debugging panel overlay
+ */
+export declare function devtoolsPlugin(options?: {
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    shortcutKey?: string;
+    onStateUpdate?: (state: DevToolsState) => void;
+}): ChatPlugin;
+
+declare interface DevToolsState {
+    messages: number;
+    events: Array<{
+        type: string;
+        time: number;
+    }>;
+    data: Record<string, unknown>;
+    currentStep: string | null;
+}
+
 export declare const DynamicForm: default_2.FC<DynamicFormProps>;
 
 declare interface DynamicFormProps {
@@ -4626,6 +4753,17 @@ declare interface DynamicFormProps {
     renderFormField?: FormFieldRenderMap;
 }
 
+/**
+ * Email Plugin — triggers emails via external API when chat events occur
+ */
+export declare function emailPlugin(options: {
+    endpoint: string;
+    template?: string;
+    headers?: Record<string, string>;
+    triggers?: ('submit' | 'flowEnd' | 'login')[];
+    mapPayload?: (data: Record<string, unknown>) => Record<string, unknown>;
+}): ChatPlugin;
+
 export declare const EmojiIcon: default_2.FC<IconProps>;
 
 export declare const EmojiPicker: default_2.FC<EmojiPickerProps>;
@@ -4783,10 +4921,22 @@ export declare interface FlowStep {
     condition?: FlowCondition;
     /** Key into ChatBotProps.components — renders a custom React component in this step */
     component?: string;
+    /** Free-text input configuration — validates user input before advancing */
+    input?: FlowStepInput;
     /** Async action to run when this step is entered (API calls, verification, etc.) */
     asyncAction?: FlowAsyncAction;
 }
 
+/** Configuration for a free-text input step with optional validation */
+export declare interface FlowStepInput {
+    /** Placeholder text for the input */
+    placeholder?: string;
+    /** Validation rules (reuses form validation) */
+    validation?: FormFieldValidation;
+    /** Transform user input before storing */
+    transform?: 'lowercase' | 'uppercase' | 'trim' | 'email';
+}
+
 export declare interface FormConfig {
     id: string;
     title?: string;
@@ -4837,6 +4987,7 @@ export declare type FormFieldRenderProps = TextFieldRenderProps | SelectFieldRen
 export declare type FormFieldType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'textarea' | 'select' | 'multiselect' | 'radio' | 'checkbox' | 'file' | 'date' | 'time' | 'hidden';
 
 export declare interface FormFieldValidation {
+    required?: boolean;
     pattern?: string;
     minLength?: number;
     maxLength?: number;
@@ -4855,6 +5006,16 @@ export declare interface HeaderConfig {
     showRestart?: boolean;
 }
 
+/**
+ * i18n Plugin — supports multiple languages with dynamic switching
+ */
+export declare function i18nPlugin(options: {
+    defaultLocale?: string;
+    translations: Translations;
+    storageKey?: string;
+    onLocaleChange?: (locale: string, ctx: PluginContext) => void;
+}): ChatPlugin;
+
 declare interface IconProps {
     size?: number;
     color?: string;
@@ -4863,6 +5024,37 @@ declare interface IconProps {
 
 export declare const ImageIcon: default_2.FC<IconProps>;
 
+/**
+ * Intent Plugin — detects user intent from text and emits intent events for dynamic routing
+ */
+export declare function intentPlugin(options?: {
+    rules?: IntentRule[];
+    onIntentDetected?: (intent: string, text: string, ctx: PluginContext) => void;
+    fallbackIntent?: string;
+}): ChatPlugin;
+
+declare interface IntentRule {
+    intent: string;
+    patterns: string[];
+    matchType?: 'contains' | 'exact' | 'regex';
+}
+
+/** Route configuration for keyword-based text matching */
+export declare interface KeywordRoute {
+    /** Patterns to match against user text */
+    patterns: string[];
+    /** Bot response message when matched */
+    response?: string;
+    /** Jump to this flow step when matched */
+    next?: string;
+    /** Case-sensitive matching (default: false) */
+    caseSensitive?: boolean;
+    /** Matching strategy (default: 'contains') */
+    matchType?: 'exact' | 'contains' | 'startsWith' | 'regex';
+    /** Priority — higher wins when multiple routes match (default: 0) */
+    priority?: number;
+}
+
 export declare const Launcher: default_2.FC<LauncherProps>;
 
 declare interface LauncherProps {
@@ -4875,6 +5067,26 @@ declare interface LauncherProps {
     zIndex?: number;
 }
 
+/**
+ * Lead Plugin — captures and stores user information as leads
+ */
+export declare function leadPlugin(options: {
+    fields?: string[];
+    endpoint?: string;
+    headers?: Record<string, string>;
+    storageKey?: string;
+    onLeadCaptured?: (lead: Record<string, unknown>, ctx: PluginContext) => void;
+}): ChatPlugin;
+
+/**
+ * Logger Plugin — logs all chatbot events for debugging or auditing
+ */
+export declare function loggerPlugin(options?: {
+    level?: LogLevel;
+    prefix?: string;
+    logger?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
+}): ChatPlugin;
+
 export declare const LoginScreen: default_2.FC<LoginScreenProps>;
 
 declare interface LoginScreenProps {
@@ -4884,6 +5096,29 @@ declare interface LoginScreenProps {
     renderFormField?: FormFieldRenderMap;
 }
 
+declare type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Markdown Plugin — transforms markdown syntax in bot messages to HTML
+ * Lightweight built-in renderer, no external dependencies.
+ */
+export declare function markdownPlugin(options?: {
+    enableBold?: boolean;
+    enableItalic?: boolean;
+    enableCode?: boolean;
+    enableLinks?: boolean;
+    enableLists?: boolean;
+    enableLineBreaks?: boolean;
+}): ChatPlugin;
+
+/**
+ * Media Plugin — adds support for rich media messages (images, videos, cards)
+ */
+export declare function mediaPlugin(options?: {
+    allowedTypes?: ('image' | 'video' | 'audio' | 'card')[];
+    onMediaRender?: (type: string, url: string) => void;
+}): ChatPlugin;
+
 export declare interface MessageAttachment {
     name: string;
     url: string;
@@ -4925,11 +5160,13 @@ export declare type MessageSender = 'bot' | 'user' | 'system';
 export declare const MinimizeIcon: default_2.FC<IconProps>;
 
 /**
- * Persistence Plugin — saves/restores chat history via localStorage
+ * Persistence Plugin — saves/restores full chat history via browser storage
  */
 export declare function persistencePlugin(options?: {
     storageKey?: string;
     storage?: 'local' | 'session';
+    maxMessages?: number;
+    ttl?: number;
 }): ChatPlugin;
 
 export declare interface PluginContext {
@@ -4959,15 +5196,28 @@ export declare class PluginManager {
     private eventHandlers;
     register(plugins: ChatPlugin[]): void;
     setContext(ctx: Omit<PluginContext, 'on' | 'emit'>): void;
+    getContext(): PluginContext | null;
     private on;
     private emit;
     init(): Promise<void>;
     onMessage(message: ChatMessage): Promise<ChatMessage>;
     onSubmit(data: Record<string, unknown>): Promise<void>;
+    /** Emit a lifecycle event to all plugins (open, close, flowEnd, stepChange, quickReply, etc.) */
+    emitEvent(type: string, payload?: unknown): void;
     destroy(): Promise<void>;
     private dispatchEvent;
 }
 
+/**
+ * Push Plugin — sends browser push notifications for new messages
+ */
+export declare function pushPlugin(options?: {
+    title?: string;
+    icon?: string;
+    onlyWhenHidden?: boolean;
+    requestPermission?: boolean;
+}): ChatPlugin;
+
 export declare const QuickReplies: default_2.FC<QuickRepliesProps>;
 
 declare interface QuickRepliesProps {
@@ -4994,12 +5244,49 @@ export declare interface RadioFieldRenderProps {
     error?: string;
 }
 
+/**
+ * Rate Limit Plugin — prevents spam by limiting message frequency
+ */
+export declare function rateLimitPlugin(options?: {
+    limit?: number;
+    window?: number;
+    onLimited?: (remaining: number) => void;
+    warningMessage?: string;
+}): ChatPlugin;
+
+/**
+ * Reminder Plugin — sends reminder messages to users after configured delays
+ */
+export declare function reminderPlugin(options?: {
+    reminders?: Array<{
+        message: string;
+        delay: number;
+        condition?: string;
+    }>;
+    onReminder?: (message: string) => void;
+}): ChatPlugin;
+
 export declare const RemoveIcon: default_2.FC<IconProps>;
 
 export declare function resolveTheme(theme?: ChatTheme): Required<ChatTheme>;
 
 export declare const RestartIcon: default_2.FC<IconProps>;
 
+declare interface ScheduledMessage {
+    message: string;
+    delay: number;
+    repeat?: boolean;
+    interval?: number;
+}
+
+/**
+ * Scheduler Plugin — triggers bot messages at scheduled times or intervals
+ */
+export declare function schedulerPlugin(options: {
+    messages?: ScheduledMessage[];
+    onScheduledMessage?: (message: string) => void;
+}): ChatPlugin;
+
 export declare const SelectField: default_2.FC<SelectFieldProps>;
 
 declare interface SelectFieldProps {
@@ -5020,6 +5307,15 @@ export declare interface SelectFieldRenderProps {
 
 export declare const SendIcon: default_2.FC<IconProps>;
 
+/**
+ * Sound Plugin — plays sound on new bot messages
+ */
+export declare function soundPlugin(options?: {
+    src?: string;
+    volume?: number;
+    onlyWhenHidden?: boolean;
+}): ChatPlugin;
+
 /** Props passed to custom components rendered in flow steps */
 export declare interface StepComponentProps {
     /** The step ID that owns this component */
@@ -5030,6 +5326,16 @@ export declare interface StepComponentProps {
     onComplete: (result?: FlowActionResult) => void;
 }
 
+/**
+ * Sync Plugin — syncs chat data with a backend endpoint
+ */
+export declare function syncPlugin(options: {
+    endpoint: string;
+    headers?: Record<string, string>;
+    syncInterval?: number;
+    sessionKey?: string;
+}): ChatPlugin;
+
 export declare const TextField: default_2.FC<TextFieldProps>;
 
 declare interface TextFieldProps {
@@ -5048,15 +5354,72 @@ export declare interface TextFieldRenderProps {
     error?: string;
 }
 
+/**
+ * Theme Plugin — switches themes dynamically and persists preference
+ */
+export declare function themePlugin(options?: {
+    defaultMode?: 'light' | 'dark';
+    storageKey?: string;
+    onThemeChange?: (mode: string, ctx: PluginContext) => void;
+    cssVariable?: string;
+}): ChatPlugin;
+
+/**
+ * Transfer Plugin — transfers chat to different departments/agents via API
+ */
+export declare function transferPlugin(options: {
+    endpoint: string;
+    headers?: Record<string, string>;
+    departments?: string[];
+    onTransfer?: (department: string, ctx: PluginContext) => void;
+    onTransferComplete?: (result: unknown, ctx: PluginContext) => void;
+    transferMessage?: string;
+}): ChatPlugin;
+
+declare type Translations = Record<string, Record<string, string>>;
+
+declare type TriggerType = 'exitIntent' | 'idle' | 'scroll' | 'pageLoad' | 'custom';
+
 export declare const TypingIndicator: default_2.FC<TypingIndicatorProps>;
 
 declare interface TypingIndicatorProps {
     color: string;
 }
 
+/**
+ * Typing Plugin — adds configurable typing delay before bot messages are shown
+ */
+export declare function typingPlugin(options?: {
+    delay?: number;
+    onTypingStart?: () => void;
+    onTypingEnd?: () => void;
+}): ChatPlugin;
+
+/**
+ * Upload Plugin — handles file uploads to external storage (S3, etc.)
+ */
+export declare function uploadPlugin(options: {
+    endpoint: string;
+    storage?: 's3' | 'gcs' | 'azure' | 'custom';
+    headers?: Record<string, string>;
+    maxSize?: number;
+    allowedTypes?: string[];
+    onUploadStart?: (file: {
+        name: string;
+        size: number;
+    }) => void;
+    onUploadComplete?: (file: {
+        name: string;
+        url: string;
+    }) => void;
+    onUploadError?: (file: {
+        name: string;
+    }, error: Error) => void;
+}): ChatPlugin;
+
 export declare function useChat(): {
     state: ChatState;
-    sendMessage: (text: string) => void;
+    sendMessage: (text: string) => Promise<void>;
     addBotMessage: (text: string, extras?: Partial<ChatMessage>) => Promise<void>;
     handleQuickReply: (value: string, label: string) => void;
     handleFormSubmit: (formId: string, data: Record<string, unknown>) => Promise<void>;
@@ -5073,12 +5436,28 @@ export declare function useChat(): {
 export declare function useChatContext(): ChatContextValue;
 
 /**
- * Webhook Plugin — sends messages/submissions to an external endpoint
+ * Validation Plugin — adds advanced validation rules for user inputs
+ */
+export declare function validationPlugin(options?: {
+    validators?: Record<string, Validator>;
+    sanitize?: boolean;
+    blockProfanity?: boolean;
+    profanityList?: string[];
+    onValidationFail?: (text: string, error: string) => void;
+}): ChatPlugin;
+
+declare type Validator = (text: string) => string | null;
+
+declare type WebhookEventType = 'message' | 'submit' | 'init' | 'destroy' | 'open' | 'close' | 'flowEnd' | 'stepChange' | 'quickReply' | 'login';
+
+/**
+ * Webhook Plugin — sends messages/submissions/lifecycle events to an external endpoint
  */
 export declare function webhookPlugin(options: {
     url: string;
     headers?: Record<string, string>;
-    events?: ('message' | 'submit' | 'init' | 'destroy')[];
+    events?: WebhookEventType[];
+    timeout?: number;
 }): ChatPlugin;
 
 export declare const WelcomeScreen: default_2.FC<WelcomeScreenProps>;