@snf/qa-bot-core 0.2.5 → 0.2.7

package/dist/types/components/HistoryButton.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+/**
+ * HistoryButton Component
+ *
+ * A button that displays saved chat history when clicked.
+ * Shows in the header when user is logged in.
+ *
+ * @returns Rendered history button
+ */
+declare const HistoryButton: React.FC;
+export default HistoryButton;

package/dist/types/components/SessionMessageTracker.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Invisible component that stores each chat message with its session ID.
+ *
+ * Problem: React-Chatbotify stores all messages in a flat list with no session
+ * boundaries. When a user has multiple conversations, there's no way to know
+ * which messages belong to which conversation. Also, RCB's history storage
+ * is opaque and unreliable for session restore.
+ *
+ * Solution: This component listens for every message injection and stores
+ * the full message content in our own localStorage. The history dropdown
+ * restores sessions directly from our storage, not RCB's.
+ *
+ * Deduplication is handled by session-utils (checks message ID).
+ *
+ * Must be rendered inside ChatBotProvider.
+ */
+declare const SessionMessageTracker: React.FC;
+export default SessionMessageTracker;

package/dist/types/config.d.ts

@@ -1,4 +1,36 @@
 import type { Settings, Flow } from 'react-chatbotify';
+/**
+ * Analytics event types fired by qa-bot-core
+ */
+export type QABotAnalyticsEventType = 'qa_bot_opened' | 'qa_bot_closed' | 'qa_new_chat_started' | 'qa_question_asked' | 'qa_response_received' | 'qa_response_error' | 'qa_response_rated' | 'qa_login_prompt_shown';
+/**
+ * Analytics event payload
+ * Fields are populated based on event type:
+ * - qa_bot_opened: sessionId
+ * - qa_bot_closed: sessionId, messageCount, durationMs
+ * - qa_new_chat_started: sessionId, previousMessageCount
+ * - qa_question_asked: sessionId, queryId, questionLength
+ * - qa_response_received: sessionId, queryId, responseTimeMs, success, responseLength, hasMetadata
+ * - qa_response_error: sessionId, queryId, errorType
+ * - qa_response_rated: sessionId, queryId, rating
+ * - qa_login_prompt_shown: sessionId
+ */
+export interface QABotAnalyticsEvent {
+    type: QABotAnalyticsEventType;
+    timestamp: number;
+    sessionId?: string;
+    queryId?: string;
+    questionLength?: number;
+    responseTimeMs?: number;
+    success?: boolean;
+    responseLength?: number;
+    hasMetadata?: boolean;
+    errorType?: string;
+    rating?: 'helpful' | 'not_helpful';
+    messageCount?: number;
+    durationMs?: number;
+    previousMessageCount?: number;
+}
 export interface QABotProps {
     apiKey: string;
     qaEndpoint: string;
@@ -31,12 +63,28 @@ export interface QABotProps {
      * - Does not affect custom flows (tickets, security, etc.)
      */
     allowAnonAccess?: boolean;
+    /**
+     * The acting user's identifier (e.g., email or username).
+     * - Sent to the backend in both headers (X-Acting-User) and body (acting_user)
+     * - Optional: if not provided, requests will be anonymous
+     */
+    actingUser?: string;
     /**
      * Custom flow steps to merge with the built-in Q&A flow.
      * Use this to add ticket creation flows, feedback flows, etc.
      * These steps will be merged into the flow object.
      */
     customFlow?: Flow;
+    /**
+     * Callback fired when trackable events occur.
+     * Use this to wire up analytics (GTM, GA4, etc.)
+     *
+     * @example
+     * onAnalyticsEvent={(event) => {
+     *   window.dataLayer?.push({ event: event.type, ...event });
+     * }}
+     */
+    onAnalyticsEvent?: (event: QABotAnalyticsEvent) => void;
 }
 /**
  * Default values for overridable props

package/dist/types/contexts/AnalyticsContext.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { QABotAnalyticsEvent } from '../config';
+interface AnalyticsContextValue {
+    trackEvent: (event: Omit<QABotAnalyticsEvent, 'timestamp'>) => void;
+}
+interface AnalyticsProviderProps {
+    onAnalyticsEvent?: (event: QABotAnalyticsEvent) => void;
+    getSessionId: () => string | null;
+    children: React.ReactNode;
+}
+export declare const AnalyticsProvider: React.FC<AnalyticsProviderProps>;
+export declare const useAnalytics: () => AnalyticsContextValue;
+export {};

package/dist/types/contexts/SessionContext.d.ts

@@ -1,10 +1,14 @@
 import React from 'react';
 interface SessionContextType {
+    getSessionId: () => string;
+    setSessionId: (sessionId: string) => void;
     resetSession: () => void;
     clearResettingFlag: () => void;
 }
 export declare const SessionProvider: React.FC<{
     children: React.ReactNode;
+    getSessionId: () => string;
+    setSessionId: (sessionId: string) => void;
     resetSession: () => void;
     clearResettingFlag: () => void;
 }>;

package/dist/types/lib.d.ts

@@ -1,4 +1,5 @@
 import QABot from './components/QABot';
+import type { QABotAnalyticsEvent } from './config';
 import './styles/index.css';
 export { QABot };
 export { FileUploadComponent } from './components/FileUploadComponent';
@@ -9,7 +10,7 @@ export { fileToBase64, filesToBase64, validateFileSize, formatFileSize } from '.
 export type { ProcessedFile } from './utils/file-utils';
 export { applyFlowSettings } from './utils/flow-settings';
 export type { FlowSettingsOptions } from './utils/flow-settings';
-export type { QABotProps, BotControllerHandle } from './config';
+export type { QABotProps, BotControllerHandle, QABotAnalyticsEvent, QABotAnalyticsEventType } from './config';
 /**
  * ===========================================
  * PROGRAMMATIC API TYPES
@@ -34,6 +35,7 @@ interface QABotConfig {
     footerText?: string;
     footerLink?: string;
     tooltipText?: string;
+    onAnalyticsEvent?: (event: QABotAnalyticsEvent) => void;
 }
 interface QABotInstance {
     addMessage: (message: string) => void;

package/dist/types/utils/fix-markdown-links.d.ts

@@ -0,0 +1,20 @@
+/**
+ * fix-markdown-links.ts
+ *
+ * PRAGMATIC HACK: This file exists because react-chatbotify's MarkdownRenderer plugin
+ * doesn't process messages injected via replaceMessages() (used for history restoration).
+ *
+ * After trying several "proper" approaches (tag manipulation, JSX conversion, HTML strings),
+ * none worked without breaking message bubble styling. This DOM post-processing approach
+ * is a pragmatic solution that:
+ * - Preserves all message styling (bubbles render correctly first)
+ * - Simply finds raw markdown link patterns [text](url) in rendered text
+ * - Replaces them with actual <a> elements
+ *
+ * Only used after history restoration, not during normal chat flow.
+ */
+/**
+ * Fixes markdown links in chat messages after they've been rendered.
+ * Call this after replaceMessages() to convert [text](url) patterns to clickable links.
+ */
+export declare const fixMarkdownLinksInDom: () => void;

package/dist/types/utils/flows/qa-flow.d.ts

@@ -1,29 +1,35 @@
 import React from 'react';
+import type { QABotAnalyticsEvent } from '../../config';
 /**
- * Creates the basic Q&A conversation flow
- * Handles questions, responses, and optional ratings
- *
- * @param {Object} params Configuration
- * @param {string} params.endpoint Q&A API endpoint (required)
- * @param {string} params.ratingEndpoint Rating API endpoint (optional)
- * @param {string} params.apiKey API key for authentication (optional)
- * @param {Function} params.sessionId Function that returns current session ID
- * @param {Function} params.isResetting Function that returns whether we're currently resetting
- * @param {boolean} params.isLoggedIn Whether the user is logged in (required)
- * @param {boolean} params.allowAnonAccess Allow Q&A without login (default: false)
- * @param {string} params.loginUrl Login URL to redirect to (optional)
- * @returns {Object} Q&A flow configuration
+ * Configuration for creating a Q&A flow
  */
-export declare const createQAFlow: ({ endpoint, ratingEndpoint, apiKey, sessionId: getSessionId, isResetting, isLoggedIn, allowAnonAccess, loginUrl }: {
-    endpoint: any;
-    ratingEndpoint: any;
-    apiKey: any;
-    sessionId: any;
+export interface CreateQAFlowParams {
+    /** Q&A API endpoint (required) */
+    endpoint: string;
+    /** Rating API endpoint (optional) */
+    ratingEndpoint?: string;
+    /** API key for authentication (optional) */
+    apiKey?: string;
+    /** Function that returns current session ID */
+    sessionId: () => string | null;
+    /** Function that returns whether we're currently resetting */
     isResetting?: () => boolean;
-    isLoggedIn: any;
+    /** Whether the user is logged in (required) */
+    isLoggedIn: boolean;
+    /** Allow Q&A without login (default: false) */
     allowAnonAccess?: boolean;
+    /** Login URL to redirect to (optional) */
     loginUrl?: string;
-}) => {
+    /** The acting user's identifier (optional) */
+    actingUser?: string;
+    /** Callback for analytics events (optional) */
+    onAnalyticsEvent?: (event: QABotAnalyticsEvent) => void;
+}
+/**
+ * Creates the basic Q&A conversation flow
+ * Handles questions, responses, and optional ratings
+ */
+export declare const createQAFlow: ({ endpoint, ratingEndpoint, apiKey, sessionId: getSessionId, isResetting, isLoggedIn, allowAnonAccess, loginUrl, actingUser, onAnalyticsEvent }: CreateQAFlowParams) => {
     qa_loop: {
         message: string;
         component: React.JSX.Element;

package/dist/types/utils/logger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Logger utility for QA Bot Core
+ *
+ * Controls debug logging via localStorage:
+ * - QA_BOT_DEBUG: Set to 'true' to enable debug logging and version info
+ *
+ * Usage for consumers:
+ *   localStorage.setItem('QA_BOT_DEBUG', 'true');  // Enable debug logs + version
+ */
+export declare const LIB_VERSION = "0.2.7";
+export declare const logger: {
+    version: () => void;
+    session: (action: string, ...args: unknown[]) => void;
+    history: (action: string, ...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};

package/dist/types/utils/session-utils.d.ts

@@ -1,2 +1,54 @@
+/**
+ * Stored message structure - minimal data needed for restore
+ */
+export interface StoredMessage {
+    id: string;
+    content: string;
+    sender: string;
+    type: string;
+    timestamp: number;
+}
+/**
+ * Session data structure
+ */
+export interface SessionMessageData {
+    messages: StoredMessage[];
+    startedAt: string;
+    preview: string;
+}
+export interface SessionMessagesStore {
+    [sessionId: string]: SessionMessageData;
+}
 export declare const generateSessionId: () => string;
-export declare const getOrCreateSessionId: () => string;
+/**
+ * Get the session messages store from localStorage
+ */
+export declare const getSessionMessagesStore: () => SessionMessagesStore;
+/**
+ * Add a message to a session's storage.
+ * Called when RcbPreInjectMessageEvent fires.
+ * Stores the full message so we can restore sessions without relying on RCB's history.
+ */
+export declare const addMessageToSession: (sessionId: string, messageId: string, messageContent: string, sender: string, type: string) => void;
+/**
+ * Get all sessions with their metadata (for history display)
+ */
+export declare const getAllSessions: () => Array<{
+    sessionId: string;
+} & SessionMessageData>;
+/**
+ * Get all stored messages for a specific session.
+ * Returns messages in the format needed for RCB's replaceMessages().
+ */
+export declare const getSessionMessages: (sessionId: string) => StoredMessage[];
+/**
+ * Get the message count for a session.
+ * Used for analytics (qa_bot_closed, qa_new_chat_started events).
+ */
+export declare const getSessionMessageCount: (sessionId: string) => number;
+/**
+ * Compute how long a session has been active (in milliseconds).
+ * Calculates the difference between now and the session's startedAt timestamp.
+ * Used for analytics (qa_bot_closed event).
+ */
+export declare const computeSessionDurationMs: (sessionId: string) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snf/qa-bot-core",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "A configurable chatbot setup for quick integration of RAG-powered Q&A and rating system",
   "main": "./dist/qa-bot-core.umd.cjs",
   "module": "./dist/qa-bot-core.js",