@qafka/react-native 2.0.0

package/dist/hooks/useChatMessages.js

@@ -0,0 +1,505 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useChatMessages = void 0;
+const react_1 = require("react");
+const QafkaSDK_1 = require("../QafkaSDK");
+const Qafka_utils_1 = require("../components/Qafka.utils");
+/**
+ * Custom hook for managing chat messages and sending
+ */
+const useChatMessages = ({ enableStreaming = true, context = {}, contextDescription, onMessageSent, onResponseReceived, onError, onNavigationSuggest, onToolSuggested, onActionResult, onStepCompleted, onFileUploadRequest, onExtractionResult, navigationLabelFormat, }) => {
+    const [messages, setMessages] = (0, react_1.useState)([]);
+    const [isTyping, setIsTyping] = (0, react_1.useState)(false);
+    const [isSending, setIsSending] = (0, react_1.useState)(false);
+    const [streamingMessage, setStreamingMessage] = (0, react_1.useState)('');
+    // active tool status pill
+    const [toolStatus, setToolStatus] = (0, react_1.useState)(null);
+    const flatListRef = (0, react_1.useRef)(null);
+    // Keep pending tool responses until AI message arrives
+    const pendingToolResponsesRef = (0, react_1.useRef)([]);
+    // accumulate `final_chunk` content across a single turn.
+    // `response.text` from the `done` event only contains what the backend
+    // streamed as `content` (the turn 1 bridge). `final_chunk` events carry the
+    // turn 2 / missing-params / error-path reply separately. We buffer them here
+    // and merge into the final assistant message in onComplete so the user sees
+    // ONE bubble with bridge + final, not two out-of-order bubbles.
+    const finalChunkBufferRef = (0, react_1.useRef)('');
+    // capture backend messageId and conversationId for the managed
+    // follow-up round-trip. messageId comes from the `done` event.
+    // conversationId currently only surfaces on the `file_uploaded` SSE event;
+    // if unavailable, the follow-up POST is skipped gracefully.
+    const lastMessageIdRef = (0, react_1.useRef)(null);
+    const lastConversationIdRef = (0, react_1.useRef)(null);
+    // guard against double-fire of postToolResult per toolKey
+    const inFlightPostToolResultRef = (0, react_1.useRef)(new Set());
+    const scrollToBottom = (animated = true) => {
+        setTimeout(() => {
+            flatListRef.current?.scrollToEnd({ animated });
+        }, 100);
+    };
+    const handleSend = async (message) => {
+        if (isSending)
+            return;
+        setIsSending(true);
+        setIsTyping(true);
+        setStreamingMessage('');
+        finalChunkBufferRef.current = '';
+        // Add user message
+        const userMessage = {
+            id: Date.now().toString(),
+            role: 'user',
+            text: message,
+            content: message,
+            timestamp: new Date(),
+        };
+        setMessages((prev) => [...prev, userMessage]);
+        onMessageSent?.(message);
+        scrollToBottom();
+        const messageToSendAI = contextDescription
+            ? `${contextDescription}\n\n${message}`
+            : message;
+        try {
+            const sdk = QafkaSDK_1.QafkaSDK.getInstance();
+            if (enableStreaming) {
+                let firstChunkReceived = false;
+                await sdk.sendMessageStream(messageToSendAI, 
+                // onChunk
+                (chunk) => {
+                    // Track first chunk silently
+                    if (!firstChunkReceived) {
+                        firstChunkReceived = true;
+                    }
+                    // 🔧 Append each incoming chunk to the accumulated message
+                    setStreamingMessage((prevMessage) => {
+                        return prevMessage + chunk;
+                    });
+                    scrollToBottom();
+                }, 
+                // onComplete
+                (response) => {
+                    setIsTyping(false);
+                    setStreamingMessage('');
+                    // capture messageId for the managed follow-up round-trip
+                    if (response.id) {
+                        lastMessageIdRef.current = response.id;
+                    }
+                    const actionButtons = (0, Qafka_utils_1.buildActionButtons)(response, navigationLabelFormat);
+                    const bridgeMessage = (response.text || '').trim();
+                    // merge turn 2 / missing-params reply from
+                    // finalChunkBufferRef into the same assistant bubble so the user
+                    // sees bridge + final reply as ONE message (not two).
+                    const finalChunkBuffered = finalChunkBufferRef.current;
+                    finalChunkBufferRef.current = '';
+                    const finalMessage = finalChunkBuffered
+                        ? bridgeMessage
+                            ? `${bridgeMessage}\n\n${finalChunkBuffered}`
+                            : finalChunkBuffered
+                        : bridgeMessage;
+                    const aiMessage = {
+                        id: response.id,
+                        role: 'assistant',
+                        text: finalMessage,
+                        content: finalMessage,
+                        timestamp: new Date(response.timestamp),
+                        actions: actionButtons.length > 0 ? actionButtons : undefined,
+                        externalSuggestions: response.externalSuggestions && response.externalSuggestions.length > 0
+                            ? response.externalSuggestions
+                            : undefined,
+                        metadata: {},
+                    };
+                    setMessages((prev) => [...prev, aiMessage]);
+                    onResponseReceived?.(response);
+                    // Process pending tool responses now that AI message has arrived
+                    if (pendingToolResponsesRef.current.length > 0) {
+                        pendingToolResponsesRef.current.forEach(({ toolKey, data, tool }) => {
+                            const position = tool?.response?.position || 'after';
+                            // if the tool has an embedded card template,
+                            // build the envelope client-side. This works for ALL execution
+                            // modes (client-side, server, server-managed); the latter also
+                            // has a redundant SSE `card` event but the registry-embedded
+                            // template wins because it arrives first.
+                            const cardEnvelope = tool?.cardTemplate?.isActive
+                                ? {
+                                    templateId: tool.cardTemplate.id,
+                                    templateSlug: tool.cardTemplate.slug,
+                                    definition: tool.cardTemplate.definition,
+                                    data,
+                                }
+                                : undefined;
+                            if (position === 'before') {
+                                // Add tool message BEFORE the AI message we just added
+                                setMessages((prev) => {
+                                    const toolMessage = {
+                                        id: Date.now().toString() + '_tool',
+                                        role: 'assistant',
+                                        text: '',
+                                        content: '',
+                                        timestamp: new Date(),
+                                        toolResponse: { toolKey, data, tool },
+                                        ...(cardEnvelope && { card: cardEnvelope }),
+                                    };
+                                    // Insert before last message (which is the AI message)
+                                    return [
+                                        ...prev.slice(0, -1),
+                                        toolMessage,
+                                        prev[prev.length - 1],
+                                    ];
+                                });
+                            }
+                            else {
+                                // Merge tool response with the AI message we just added
+                                setMessages((prev) => {
+                                    const lastMessage = prev[prev.length - 1];
+                                    const updatedMessage = {
+                                        ...lastMessage,
+                                        toolResponse: { toolKey, data, tool },
+                                        ...(cardEnvelope && { card: cardEnvelope }),
+                                    };
+                                    return [...prev.slice(0, -1), updatedMessage];
+                                });
+                            }
+                            const sdk = QafkaSDK_1.QafkaSDK.getInstance();
+                            sdk.addToolResponse(toolKey, data, tool);
+                        });
+                        // Clear pending queue
+                        pendingToolResponsesRef.current = [];
+                        // Scroll after tool responses are processed
+                        scrollToBottom();
+                    }
+                    // Handle navigation suggestion
+                    if (response.navigationSuggestion && onNavigationSuggest) {
+                        onNavigationSuggest(response.navigationSuggestion);
+                    }
+                    setIsSending(false);
+                }, 
+                // onError
+                (err) => {
+                    handleError(err);
+                }, context, contextDescription, 
+                // onToolSuggested
+                async (tools, conversationId, messageId) => {
+                    if (conversationId) {
+                        lastConversationIdRef.current = conversationId;
+                    }
+                    if (messageId) {
+                        lastMessageIdRef.current = messageId;
+                    }
+                    if (onToolSuggested) {
+                        // Tracks tools the consumer's `onToolSuggested` handler explicitly
+                        // called `addResponse` for. The auto-fire loop below uses this — NOT
+                        // `pendingToolResponsesRef` — to decide whether to inject an empty
+                        // payload. Why: when the consumer's handler is async and the assistant
+                        // message lands before its `await` resolves, `addToolResponseToWidget`
+                        // attaches the real data AND drains it from the pending queue
+                        // (see filter at the start of `setMessages` below). The auto-fire then
+                        // observes `!alreadyPending` and overwrites the consumer's payload
+                        // with `{}`. Tracking handled-by-consumer separately keeps the two
+                        // signals from collapsing into one.
+                        const consumerHandledKeys = new Set();
+                        const addToolResponseToWidget = (data, tool, mode = 'both') => {
+                            const toolKey = tool?.key ?? tool?.name ?? '';
+                            const updatesUI = mode === 'ui' || mode === 'both';
+                            const commits = mode === 'data' || mode === 'both';
+                            consumerHandledKeys.add(toolKey);
+                            // 🔧 Always add to pending queue first (outside setMessages to avoid batching issues)
+                            if (updatesUI) {
+                                pendingToolResponsesRef.current.push({
+                                    toolKey,
+                                    data,
+                                    tool,
+                                });
+                                // Merge tool response into the last assistant message. For
+                                // multi-step managed flows, each step appends content
+                                // to the SAME assistant message via final_chunk streaming —
+                                // and emits a fresh tool suggestion. Without replacing the
+                                // toolResponse here, the UI stays frozen on step 1's data.
+                                // Always overwrite with the latest data; voice handles the
+                                // equivalent via renderedTools upsert by toolKey.
+                                setMessages((prev) => {
+                                    const lastMsg = prev[prev.length - 1];
+                                    if (lastMsg && lastMsg.role === 'assistant') {
+                                        pendingToolResponsesRef.current =
+                                            pendingToolResponsesRef.current.filter((p) => p.toolKey !== toolKey);
+                                        // attach the card envelope when the tool's
+                                        // registry entry includes a card template.
+                                        const cardEnvelope = tool?.cardTemplate?.isActive
+                                            ? {
+                                                templateId: tool.cardTemplate.id,
+                                                templateSlug: tool.cardTemplate.slug,
+                                                definition: tool.cardTemplate.definition,
+                                                data,
+                                            }
+                                            : undefined;
+                                        const updatedMsg = {
+                                            ...lastMsg,
+                                            toolResponse: { toolKey, data, tool },
+                                            ...(cardEnvelope && { card: cardEnvelope }),
+                                        };
+                                        return [...prev.slice(0, -1), updatedMsg];
+                                    }
+                                    return prev; // No assistant message yet; pending queue handles it in onComplete
+                                });
+                                // Register in SDK
+                                const sdk = QafkaSDK_1.QafkaSDK.getInstance();
+                                sdk.addToolResponse(toolKey, data, tool);
+                            }
+                            // Custom-with-AI round-trip
+                            // In managed follow-up mode the SDK should POST the
+                            // tool result back to the backend, which runs a second LLM turn
+                            // and streams a `final_chunk` reply.
+                            if (commits && tool?.executionMode === 'custom-with-ai') {
+                                const conversationId = lastConversationIdRef.current;
+                                const messageId = lastMessageIdRef.current;
+                                if (conversationId && messageId) {
+                                    // Guard: prevent double-fire of postToolResult for the
+                                    // SAME (messageId, toolKey) pair. Multi-step managed
+                                    // tools fire the same toolKey across multiple messages —
+                                    // those are legitimately separate calls and must not be
+                                    // blocked. Keying by messageId+toolKey only blocks the
+                                    // genuine double-fire (developer calling addResponse twice
+                                    // for one tool suggestion).
+                                    const inFlightKey = `${messageId}:${toolKey}`;
+                                    if (inFlightPostToolResultRef.current.has(inFlightKey)) {
+                                        if (__DEV__) {
+                                            console.warn('[Qafka] postToolResult already in-flight for', inFlightKey);
+                                        }
+                                    }
+                                    else {
+                                        inFlightPostToolResultRef.current.add(inFlightKey);
+                                        setToolStatus({
+                                            toolKey,
+                                            message: tool.loadingMessage || 'Loading…',
+                                            stage: 'processing',
+                                        });
+                                        sdk.postToolResult({
+                                            conversationId,
+                                            messageId,
+                                            toolKey,
+                                            data,
+                                            // Forward the Qafka <context> prop so turn-2 has
+                                            // the same runtime context as turn-1.
+                                            sdkContext: context,
+                                        }, (content) => {
+                                            setToolStatus(null);
+                                            setMessages((prev) => {
+                                                const lastMsg = prev[prev.length - 1];
+                                                if (lastMsg && lastMsg.role === 'assistant') {
+                                                    const nextText = (lastMsg.text || '') + content;
+                                                    return [
+                                                        ...prev.slice(0, -1),
+                                                        {
+                                                            ...lastMsg,
+                                                            text: nextText,
+                                                            content: nextText,
+                                                        },
+                                                    ];
+                                                }
+                                                return prev;
+                                            });
+                                        }, () => {
+                                            setToolStatus(null);
+                                            inFlightPostToolResultRef.current.delete(inFlightKey);
+                                        }, (err) => {
+                                            setToolStatus(null);
+                                            inFlightPostToolResultRef.current.delete(inFlightKey);
+                                            if (__DEV__) {
+                                                console.warn('[Qafka] postToolResult error:', err.message);
+                                            }
+                                        }, 
+                                        // Card Template: attach card envelope to last assistant message
+                                        (cardEnvelope) => {
+                                            setMessages((prev) => {
+                                                const lastMsg = prev[prev.length - 1];
+                                                if (lastMsg && lastMsg.role === 'assistant') {
+                                                    return [
+                                                        ...prev.slice(0, -1),
+                                                        { ...lastMsg, card: cardEnvelope },
+                                                    ];
+                                                }
+                                                return prev;
+                                            });
+                                        }).catch(() => {
+                                            setToolStatus(null);
+                                            inFlightPostToolResultRef.current.delete(inFlightKey);
+                                        });
+                                    }
+                                }
+                                else if (__DEV__) {
+                                    console.warn('[Qafka] Skipping tool round-trip: missing conversationId or messageId');
+                                }
+                            }
+                        };
+                        // Important: wait for tool processing before continuing
+                        await onToolSuggested(tools, addToolResponseToWidget);
+                        // Auto-trigger UI for uiConfig-only tools (no endpoint/action/fileInput).
+                        // Skips the managed follow-up mode: those tools' contract is that the consumer
+                        // handler computes the data (often async, e.g. fetching cities)
+                        // and then calls addResponse with it. Auto-firing with `{}` here
+                        // races against the consumer's async handler — its empty payload
+                        // wins the in-flight postToolResult guard, and the real data
+                        // arrives too late, leaving turn-2 LLM narrating an empty result.
+                        //
+                        // Gate on `consumerHandledKeys`, not `pendingToolResponsesRef`: when the
+                        // consumer's async handler resolves AFTER the assistant message has
+                        // landed, `addToolResponseToWidget` attaches the real data and removes
+                        // the entry from pending — so a pending-only check would (wrongly) see
+                        // the slot as empty and overwrite the consumer's payload with `{}`.
+                        for (const tool of tools) {
+                            if (tool?.executionMode === 'custom-with-ai')
+                                continue;
+                            const m = tool.modules || {};
+                            if (tool.uiConfig && !m.hasEndpoint && !m.hasActions && !m.hasFileInput) {
+                                if (!consumerHandledKeys.has(tool.key)) {
+                                    addToolResponseToWidget({}, tool);
+                                }
+                            }
+                        }
+                    }
+                }, undefined, // isInitialMessage
+                // onActionResult — attach to message + forward to user callback
+                (results) => {
+                    setMessages((prev) => {
+                        const lastMsg = prev[prev.length - 1];
+                        if (lastMsg && lastMsg.role === 'assistant') {
+                            return [
+                                ...prev.slice(0, -1),
+                                { ...lastMsg, actionResults: [...(lastMsg.actionResults || []), ...results] },
+                            ];
+                        }
+                        return prev;
+                    });
+                    onActionResult?.(results);
+                }, 
+                // onStepCompleted — attach to message + forward to user callback
+                (result) => {
+                    setMessages((prev) => {
+                        const lastMsg = prev[prev.length - 1];
+                        if (lastMsg && lastMsg.role === 'assistant') {
+                            return [
+                                ...prev.slice(0, -1),
+                                {
+                                    ...lastMsg,
+                                    completedSteps: [
+                                        ...(lastMsg.completedSteps || []),
+                                        { tool: result.tool, step: result.step, data: result.data },
+                                    ],
+                                },
+                            ];
+                        }
+                        return prev;
+                    });
+                    onStepCompleted?.(result);
+                }, 
+                // onFileUploadRequest — also capture conversationId if present
+                (request) => {
+                    if (request && typeof request.conversationId === 'string') {
+                        lastConversationIdRef.current = request.conversationId;
+                    }
+                    onFileUploadRequest?.(request);
+                }, 
+                // onExtractionResult
+                onExtractionResult, 
+                // onToolStatus: show pill
+                (status) => {
+                    setToolStatus(status);
+                }, 
+                // onToolResultPayload: merge into last AI message
+                (payload) => {
+                    setToolStatus(null);
+                    setMessages((prev) => {
+                        const lastMsg = prev[prev.length - 1];
+                        if (lastMsg && lastMsg.role === 'assistant') {
+                            return [
+                                ...prev.slice(0, -1),
+                                {
+                                    ...lastMsg,
+                                    toolResponse: {
+                                        toolKey: payload.toolKey,
+                                        data: payload.data,
+                                        tool: {
+                                            key: payload.toolKey,
+                                            uiConfig: payload.uiConfig,
+                                        },
+                                    },
+                                },
+                            ];
+                        }
+                        return prev;
+                    });
+                }, 
+                // onFinalChunk: accumulate into finalChunkBufferRef +
+                // mirror into streamingMessage so the user sees it live. onComplete
+                // merges buffer with response.text so one assistant bubble gets the
+                // full text (bridge + turn 2 reply) instead of two separate ones.
+                (content) => {
+                    setToolStatus(null);
+                    finalChunkBufferRef.current +=
+                        (finalChunkBufferRef.current ? '\n\n' : '') + content;
+                    setStreamingMessage((prev) => {
+                        const sep = prev && !prev.endsWith('\n') ? '\n\n' : '';
+                        return prev + sep + content;
+                    });
+                });
+            }
+            else {
+                // Non-streaming
+                const response = await sdk.sendMessage(message, context, contextDescription);
+                const aiMessage = {
+                    id: response.id,
+                    role: 'assistant',
+                    text: response.text || '',
+                    content: response.text || '',
+                    timestamp: new Date(response.timestamp),
+                    externalSuggestions: response.externalSuggestions && response.externalSuggestions.length > 0
+                        ? response.externalSuggestions
+                        : undefined,
+                    metadata: {},
+                };
+                setMessages((prev) => [...prev, aiMessage]);
+                onResponseReceived?.(response);
+                if (response.navigationSuggestion && onNavigationSuggest) {
+                    onNavigationSuggest(response.navigationSuggestion);
+                }
+                scrollToBottom();
+                setIsTyping(false);
+                setIsSending(false);
+            }
+        }
+        catch (err) {
+            handleError(err);
+        }
+    };
+    const handleError = (err) => {
+        setIsTyping(false);
+        setStreamingMessage('');
+        setIsSending(false);
+        setToolStatus(null);
+        finalChunkBufferRef.current = '';
+        const errorMessage = err.message || 'Unknown error';
+        onError?.(err instanceof Error ? err : new Error(errorMessage));
+        // Default fallback bubble. Apps that want a localized or custom error
+        // surface should handle the `onError` callback above and suppress this
+        // bubble in their own UI (e.g. by clearing messages on error).
+        const errorMsg = {
+            id: Date.now().toString(),
+            role: 'assistant',
+            text: '⚠️ Something went wrong.',
+            content: '⚠️ Something went wrong.',
+            timestamp: new Date(),
+        };
+        setMessages((prev) => [...prev, errorMsg]);
+    };
+    return {
+        messages,
+        isTyping,
+        isSending,
+        streamingMessage,
+        toolStatus,
+        flatListRef,
+        handleSend,
+        setMessages,
+        setIsTyping,
+        setStreamingMessage,
+    };
+};
+exports.useChatMessages = useChatMessages;

package/dist/hooks/useContextManager.d.ts

@@ -0,0 +1,12 @@
+export interface UseContextManagerOptions {
+    initialContext?: Record<string, any>;
+    debounceMs?: number;
+}
+export interface UseContextManagerResult {
+    currentContext: Record<string, any>;
+    updateContext: (newContext: Record<string, any>) => void;
+}
+/**
+ * Custom hook for managing context with debouncing
+ */
+export declare const useContextManager: ({ initialContext, debounceMs, }?: UseContextManagerOptions) => UseContextManagerResult;

package/dist/hooks/useContextManager.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useContextManager = void 0;
+const react_1 = require("react");
+/**
+ * Custom hook for managing context with debouncing
+ */
+const useContextManager = ({ initialContext = {}, debounceMs = 500, } = {}) => {
+    const [currentContext, setCurrentContext] = (0, react_1.useState)(initialContext);
+    const debounceTimer = (0, react_1.useRef)(null);
+    const updateContext = (newContext) => {
+        // Clear existing timer
+        if (debounceTimer.current) {
+            clearTimeout(debounceTimer.current);
+        }
+        // Set new timer
+        debounceTimer.current = setTimeout(() => {
+            setCurrentContext(newContext);
+        }, debounceMs);
+    };
+    // Cleanup on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            if (debounceTimer.current) {
+                clearTimeout(debounceTimer.current);
+            }
+        };
+    }, []);
+    // Handle external context updates
+    (0, react_1.useEffect)(() => {
+        if (initialContext) {
+            // Use JSON.stringify for deep comparison to avoid infinite loops
+            // when a new object reference is passed with the same content
+            const prevContextStr = JSON.stringify(currentContext);
+            const newContextStr = JSON.stringify(initialContext);
+            if (prevContextStr !== newContextStr) {
+                updateContext(initialContext);
+            }
+        }
+    }, [initialContext, currentContext]);
+    return {
+        currentContext,
+        updateContext,
+    };
+};
+exports.useContextManager = useContextManager;

package/dist/hooks/useProjectTheme.d.ts

@@ -0,0 +1,19 @@
+import { Theme } from '../themes';
+import { ThemeOverride } from '../themes/types';
+interface UseProjectThemeOptions {
+    sdkReady: boolean;
+    themeName: 'light' | 'dark' | Theme;
+    customTheme?: Theme;
+    themeOverride?: ThemeOverride;
+    subProjectId?: string;
+}
+interface UseProjectThemeResult {
+    theme: Theme;
+    isLoadingTheme: boolean;
+    greeting: string | null;
+    initialMessage: string | null;
+    isInitialMessageEnabled: boolean;
+    voiceEnabled: boolean;
+}
+export declare function useProjectTheme({ sdkReady, themeName, customTheme, themeOverride, subProjectId, }: UseProjectThemeOptions): UseProjectThemeResult;
+export {};