@snf/qa-bot-core 0.2.30-rc.9 → 0.2.30

package/dist/types/config.d.ts

@@ -2,7 +2,7 @@ import type { Settings, Flow } from 'react-chatbotify';
 /**
  * Analytics event types fired by qa-bot-core
  */
-export type QABotAnalyticsEventType = 'chatbot_open' | 'chatbot_close' | 'chatbot_new_chat' | 'chatbot_question_sent' | 'chatbot_answer_received' | 'chatbot_answer_error' | 'chatbot_rating_sent' | 'chatbot_login_prompt_shown' | 'chatbot_login_clicked' | 'chatbot_link_clicked';
+export type QABotAnalyticsEventType = 'chatbot_open' | 'chatbot_close' | 'chatbot_new_chat' | 'chatbot_question_sent' | 'chatbot_answer_received' | 'chatbot_answer_error' | 'chatbot_rating_sent' | 'chatbot_login_prompt_shown' | 'chatbot_login_clicked' | 'chatbot_link_clicked' | 'chatbot_turnstile_shown' | 'chatbot_turnstile_completed' | 'chatbot_turnstile_error';
 /**
  * Analytics event payload
  *
@@ -50,6 +50,19 @@ export interface QABotProps {
     qaEndpoint: string;
     welcomeMessage: string;
     ratingEndpoint?: string;
+    /**
+     * Endpoint for the capabilities API (e.g., /api/v1/capabilities).
+     * The wrapper can use this to fetch dynamic capability buttons on load.
+     * Core does not fetch from this — it's a passthrough for wrappers.
+     */
+    capabilitiesEndpoint?: string;
+    /**
+     * Rating endpoint for agent-handled responses (non-RAG).
+     * When the response metadata includes `rating_target: "agent"`,
+     * ratings are POSTed here instead of `ratingEndpoint`.
+     * Payload: { query_id, rating: "helpful"|"not_helpful", feedback? }
+     */
+    agentRatingEndpoint?: string;
     primaryColor?: string;
     secondaryColor?: string;
     botName?: string;
@@ -83,6 +96,16 @@ export interface QABotProps {
      * - Optional: if not provided, requests will be anonymous
      */
     actingUser?: string;
+    /**
+     * Cloudflare Turnstile site key for bot protection.
+     * When provided, an invisible Turnstile widget is rendered on mount
+     * to silently verify the user.  The token is attached to every query
+     * automatically.  If silent verification fails, the backend's
+     * visible-challenge flow kicks in as a fallback.
+     *
+     * Omit or pass empty string to disable Turnstile entirely on the frontend.
+     */
+    turnstileSiteKey?: string;
     /**
      * Custom flow steps to merge with the built-in Q&A flow.
      * Use this to add ticket creation flows, feedback flows, etc.

package/dist/types/hooks/useTurnstile.d.ts

@@ -0,0 +1,27 @@
+/**
+ * useTurnstile — silent background Turnstile verification.
+ *
+ * Renders an invisible Cloudflare Turnstile widget on mount.  Most legitimate
+ * users get a token automatically (no UI).  The token is exposed so the
+ * qa-flow can attach it to every request.
+ *
+ * If silent verification fails (Cloudflare deems the visitor suspicious),
+ * `status` becomes 'failed' and the qa-flow falls back to the existing
+ * visible-challenge path (backend returns requires_turnstile, widget shown
+ * in chat).
+ *
+ * Turnstile tokens expire after ~300 s.  The widget's built-in
+ * `refresh-expired: auto` handles re-issuing before expiry.
+ */
+export type TurnstileStatus = 'idle' | 'loading' | 'verified' | 'failed';
+export interface UseTurnstileResult {
+    /** Current Turnstile token, or null if not yet verified / failed. */
+    token: string | null;
+    /** Lifecycle status of the silent verification. */
+    status: TurnstileStatus;
+}
+/**
+ * @param siteKey  Cloudflare Turnstile site key.  Pass `undefined` or empty
+ *                 string to disable (hook becomes a no-op).
+ */
+export declare function useTurnstile(siteKey: string | undefined): UseTurnstileResult;

package/dist/types/lib.d.ts

@@ -22,10 +22,13 @@ interface QABotConfig {
     apiKey: string;
     qaEndpoint: string;
     ratingEndpoint?: string;
+    capabilitiesEndpoint?: string;
+    agentRatingEndpoint?: string;
     defaultOpen?: boolean;
     embedded?: boolean;
     isLoggedIn: boolean;
     allowAnonAccess?: boolean;
+    turnstileSiteKey?: string;
     welcomeMessage: string;
     primaryColor?: string;
     secondaryColor?: string;

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

@@ -6,8 +6,10 @@ import type { AnalyticsEventInput } from '../../contexts/AnalyticsContext';
 export interface CreateQAFlowParams {
     /** Q&A API endpoint (required) */
     endpoint: string;
-    /** Rating API endpoint (optional) */
+    /** Rating API endpoint for RAG responses (optional) */
     ratingEndpoint?: string;
+    /** Rating API endpoint for agent responses (optional) */
+    agentRatingEndpoint?: string;
     /** API key for authentication (optional) */
     apiKey?: string;
     /** Function that returns current session ID */
@@ -28,12 +30,19 @@ export interface CreateQAFlowParams {
     actingUser?: string;
     /** Enriched analytics tracker (adds common fields automatically) */
     trackEvent?: (event: AnalyticsEventInput) => void;
+    /**
+     * Returns the current silent Turnstile token (from useTurnstile hook).
+     * When available, attached to every request so the backend can verify
+     * without prompting.  When null, the backend's free-query allowance
+     * applies, and the visible challenge is the fallback.
+     */
+    getTurnstileToken?: () => string | null;
 }
 /**
  * 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, trackEvent }: CreateQAFlowParams) => {
+export declare const createQAFlow: ({ endpoint, ratingEndpoint, agentRatingEndpoint, apiKey, sessionId: getSessionId, isResetting, isLoggedIn, allowAnonAccess, loginUrl, actingUser, trackEvent, getTurnstileToken, }: CreateQAFlowParams) => {
     qa_loop: {
         message: string;
         component: React.JSX.Element;
@@ -44,7 +53,7 @@ export declare const createQAFlow: ({ endpoint, ratingEndpoint, apiKey, sessionI
     };
 } | {
     qa_loop: {
-        message: (chatState: any) => Promise<"Thanks for the feedback! Feel free to ask another question." | "Verification failed. Please try your question again." | "I had trouble processing your question after verification. Please try again." | "Please verify you're human to continue." | "I apologize, but I'm having trouble processing your question. Please try again later.">;
+        message: (chatState: any) => Promise<"Thanks for the feedback!" | "One moment — verifying your session…" | "I apologize, but I'm having trouble processing your question. Please try again later.">;
         options: (chatState: any) => string[];
         renderMarkdown: string[];
         chatDisabled: boolean;

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

@@ -7,12 +7,14 @@
  * Usage for consumers:
  *   localStorage.setItem('QA_BOT_DEBUG', 'true');  // Enable debug logs + version
  */
-export declare const LIB_VERSION = "0.2.30-rc.9";
+export declare const LIB_VERSION = "0.2.30";
+export declare function isDebugEnabled(): boolean;
 export declare const logger: {
     version: () => void;
     session: (action: string, ...args: unknown[]) => void;
     history: (action: string, ...args: unknown[]) => void;
     message: (action: string, data: Record<string, unknown>) => void;
+    turnstile: (action: string, ...args: unknown[]) => void;
     warn: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snf/qa-bot-core",
-  "version": "0.2.30-rc.9",
+  "version": "0.2.30",
   "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",