@qafka/react-native 2.0.0

package/dist/hooks/useProjectTheme.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useProjectTheme = useProjectTheme;
+const react_1 = require("react");
+const themes_1 = require("../themes");
+const deepMerge_1 = require("../utils/deepMerge");
+const QafkaSDK_1 = require("../QafkaSDK");
+const storage_1 = require("../services/storage");
+const THEME_CACHE_PREFIX = '@qafka/theme:';
+const getThemeCacheKey = (subProjectId) => `${THEME_CACHE_PREFIX}${subProjectId ?? 'main'}`;
+const defined = (obj) => {
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined && v !== null)
+            result[k] = v;
+    }
+    return result;
+};
+function mapRawThemeToOverride(rawTheme) {
+    return {
+        colors: defined({
+            background: rawTheme.containerBackground,
+            userBubble: rawTheme.userMessageBackground,
+            userBubbleText: rawTheme.userMessageText,
+            aiBubble: rawTheme.aiMessageBackground,
+            aiBubbleText: rawTheme.aiMessageText,
+            inputBackground: rawTheme.inputBackground,
+            text: rawTheme.inputText,
+            inputBorder: rawTheme.inputBorder,
+            buttonBackground: rawTheme.sendButtonBackground,
+            buttonText: rawTheme.sendButtonText,
+        }),
+        typography: defined({
+            fontSize: defined({ md: rawTheme.fontSize }),
+            fontWeight: defined({
+                regular: '400',
+                medium: '500',
+                semibold: '600',
+                bold: rawTheme.fontWeight,
+            }),
+            lineHeight: defined({ normal: rawTheme.lineHeight }),
+        }),
+        borderRadius: defined({
+            lg: rawTheme.userMessageBorderRadius ?? rawTheme.aiMessageBorderRadius,
+            xl: rawTheme.inputBorderRadius,
+        }),
+        spacing: defined({
+            md: rawTheme.containerPadding,
+            lg: rawTheme.userMessagePadding ?? rawTheme.aiMessagePadding,
+        }),
+        messages: {
+            user: {
+                padding: rawTheme.userMessagePadding ?? 12,
+                maxWidth: rawTheme.userMessageMaxWidth ?? 70,
+            },
+            ai: {
+                padding: rawTheme.aiMessagePadding ?? 12,
+                maxWidth: rawTheme.aiMessageMaxWidth ?? 70,
+            },
+        },
+    };
+}
+function useProjectTheme({ sdkReady, themeName, customTheme, themeOverride, subProjectId, }) {
+    const [apiThemeOverride, setApiThemeOverride] = (0, react_1.useState)(null);
+    const [greeting, setGreeting] = (0, react_1.useState)(null);
+    const [initialMessage, setInitialMessage] = (0, react_1.useState)(null);
+    const [isInitialMessageEnabled, setIsInitialMessageEnabled] = (0, react_1.useState)(false);
+    // Start as `true` to gate the initial render until we either hit cache
+    // or finish the API fetch. Otherwise the first paint shows ChatPage's
+    // English fallback greeting before the project-specific one arrives.
+    const [isLoadingTheme, setIsLoadingTheme] = (0, react_1.useState)(true);
+    const [voiceEnabled, setVoiceEnabled] = (0, react_1.useState)(false);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        const applyThemeData = (themeData) => {
+            if (!themeData)
+                return;
+            const modeTheme = typeof themeName === 'string' ? themeName : 'light';
+            const rawTheme = themeData[modeTheme];
+            if (rawTheme) {
+                setApiThemeOverride(mapRawThemeToOverride(rawTheme));
+            }
+            if (themeData.greetingMessage)
+                setGreeting(themeData.greetingMessage);
+            if (themeData.initialMessage)
+                setInitialMessage(themeData.initialMessage);
+            if (themeData.isInitialMessageEnabled)
+                setIsInitialMessageEnabled(true);
+            if (themeData.features?.voiceEnabled)
+                setVoiceEnabled(true);
+        };
+        const loadTheme = async () => {
+            const cacheKey = getThemeCacheKey(subProjectId);
+            // Step 1 — stale-while-revalidate: hydrate from cache so a warm open
+            // paints the correct branded greeting immediately.
+            try {
+                const cached = await storage_1.storage.getItem(cacheKey);
+                if (cached && !cancelled) {
+                    applyThemeData(JSON.parse(cached));
+                    setIsLoadingTheme(false);
+                }
+            }
+            catch {
+                // Ignore cache read failures (corrupt JSON, native module missing, etc.)
+            }
+            // Step 2 — prefer the prefetch promise (started inside QafkaSDK.initialize
+            // parallel to attestation). Theme is gated by API key only, not session
+            // token, so it can resolve before sdkReady. Falls back to a direct call
+            // only when sdkReady — covers hosts that bypass `<Qafka>`-driven init.
+            const sdk = QafkaSDK_1.QafkaSDK.getInstance();
+            const prefetch = sdk.getThemePrefetch();
+            let themeData = null;
+            try {
+                if (prefetch) {
+                    themeData = await prefetch;
+                }
+                else if (sdkReady) {
+                    themeData = await sdk.getProjectTheme();
+                }
+            }
+            catch {
+                // Theme load failed — cache (if any) already applied above.
+            }
+            if (cancelled)
+                return;
+            if (themeData) {
+                applyThemeData(themeData);
+                try {
+                    await storage_1.storage.setItem(cacheKey, JSON.stringify(themeData));
+                }
+                catch {
+                    // Cache write failures are non-fatal.
+                }
+            }
+            if (!cancelled)
+                setIsLoadingTheme(false);
+        };
+        loadTheme();
+        return () => {
+            cancelled = true;
+        };
+    }, [sdkReady, themeName, subProjectId]);
+    const theme = (0, react_1.useMemo)(() => {
+        let baseTheme;
+        if (customTheme) {
+            baseTheme = customTheme;
+        }
+        else if (typeof themeName === 'string') {
+            baseTheme = (0, themes_1.getTheme)(themeName);
+        }
+        else {
+            baseTheme = themeName;
+        }
+        if (apiThemeOverride) {
+            baseTheme = (0, deepMerge_1.deepMerge)(baseTheme, apiThemeOverride);
+        }
+        if (themeOverride) {
+            baseTheme = (0, deepMerge_1.deepMerge)(baseTheme, themeOverride);
+        }
+        return baseTheme;
+    }, [themeName, customTheme, themeOverride, apiThemeOverride]);
+    return { theme, isLoadingTheme, greeting, initialMessage, isInitialMessageEnabled, voiceEnabled };
+}

package/dist/hooks/useSDK.d.ts

@@ -0,0 +1,31 @@
+export interface UseSDKOptions {
+    apiUrl?: string;
+    subProjectId?: string;
+    /** Project identifier when the runtime config registers more than one project. */
+    projectId?: string;
+    /**
+     * BCP 47 locale. Forwarded to the SDK on init and re-applied any
+     * time it changes — keeps `sdkContext.locale` in sync with the host app.
+     */
+    locale?: string;
+    onReady?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface UseSDKResult {
+    sdkReady: boolean;
+    error: string | null;
+    /**
+     * Dev-only: the resolved developmentKey from `qafka.config.js`. Null in
+     * production builds (Metro dead-code-eliminates the dev config branch).
+     * Used by `useVoiceChat` whose WebSocket auth still relies on apiKey.
+     */
+    resolvedApiKey: string | null;
+    /** Backend URL the SDK is actually using (after dev-config override). */
+    resolvedApiUrl: string | undefined;
+    initializeSDK: () => Promise<void>;
+    loadHistory: () => Promise<any[]>;
+}
+/**
+ * Custom hook for managing SDK initialization and lifecycle
+ */
+export declare const useSDK: ({ apiUrl, subProjectId, projectId, locale, onReady, onError, }: UseSDKOptions) => UseSDKResult;

package/dist/hooks/useSDK.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSDK = void 0;
+const react_1 = require("react");
+const QafkaSDK_1 = require("../QafkaSDK");
+const runtime_config_loader_1 = require("../runtime-config-loader");
+const resolve_project_config_1 = require("../resolve-project-config");
+/**
+ * Custom hook for managing SDK initialization and lifecycle
+ */
+const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, }) => {
+    const [sdkReady, setSdkReady] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [resolvedApiKey, setResolvedApiKey] = (0, react_1.useState)(null);
+    const [resolvedApiUrl, setResolvedApiUrl] = (0, react_1.useState)(apiUrl);
+    const onReadyRef = (0, react_1.useRef)(onReady);
+    const onErrorRef = (0, react_1.useRef)(onError);
+    onReadyRef.current = onReady;
+    onErrorRef.current = onError;
+    const initializeSDK = async () => {
+        let apiKey = null;
+        let resolvedUrl = apiUrl;
+        if (__DEV__) {
+            // Dev path: load qafka.config.js, pick developmentKey for the current project.
+            // Metro dead-code elimination removes this branch entirely in production
+            // builds, so qafka.config.js never lands in the prod bundle.
+            try {
+                const cfg = (0, resolve_project_config_1.resolveProjectConfig)({ apiUrl, projectId }, (0, runtime_config_loader_1.loadRuntimeConfig)());
+                apiKey = cfg.apiKey;
+                resolvedUrl = cfg.apiUrl;
+            }
+            catch (err) {
+                if (__DEV__) {
+                    console.warn('[Qafka] Dev config missing or invalid:', err instanceof Error ? err.message : err);
+                }
+            }
+        }
+        // Expose resolved values so `useVoiceChat` (WebSocket auth still
+        // apiKey-based) can pick up the dev key. Null in prod.
+        setResolvedApiKey(apiKey);
+        setResolvedApiUrl(resolvedUrl);
+        try {
+            const sdk = QafkaSDK_1.QafkaSDK.getInstance();
+            await sdk.initialize({
+                apiKey, // null in prod; developmentKey in dev
+                apiUrl: resolvedUrl,
+                subProjectId,
+                locale,
+                onStatusChange: (status) => {
+                    if (status === 'ready') {
+                        setSdkReady(true);
+                        onReadyRef.current?.();
+                    }
+                    else if (status === 'error') {
+                        setError('Failed to initialize SDK');
+                        onErrorRef.current?.(new Error('SDK initialization failed'));
+                    }
+                },
+            });
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Unknown error';
+            setError(errorMessage);
+            onErrorRef.current?.(err instanceof Error ? err : new Error(errorMessage));
+        }
+    };
+    const loadHistory = async () => {
+        try {
+            const sdk = QafkaSDK_1.QafkaSDK.getInstance();
+            return await sdk.getConversationHistory();
+        }
+        catch {
+            return [];
+        }
+    };
+    (0, react_1.useEffect)(() => {
+        const sdk = QafkaSDK_1.QafkaSDK.getInstance();
+        setSdkReady(false);
+        setError(null);
+        initializeSDK();
+        return () => {
+            setSdkReady(false);
+            sdk.destroy();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [subProjectId, projectId]);
+    // re-apply locale changes without forcing a full SDK re-init —
+    // the host app may switch language mid-session.
+    (0, react_1.useEffect)(() => {
+        if (!sdkReady)
+            return;
+        QafkaSDK_1.QafkaSDK.getInstance().setLocale(locale ?? null);
+    }, [locale, sdkReady]);
+    return {
+        sdkReady,
+        error,
+        resolvedApiKey,
+        resolvedApiUrl,
+        initializeSDK,
+        loadHistory,
+    };
+};
+exports.useSDK = useSDK;

package/dist/hooks/useVoiceChat.d.ts

@@ -0,0 +1,110 @@
+export type VoiceChatState = 'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking';
+export interface VoiceToolStatus {
+    toolCallId: string;
+    toolKey: string;
+    loadingMessage: string;
+}
+export type VoiceRenderedTool = {
+    kind?: 'tool';
+    toolCallId: string;
+    toolKey: string;
+    data: any;
+    tool: any;
+} | {
+    kind: 'display';
+    toolCallId: string;
+    items: Array<{
+        label: string;
+        value: string;
+        copyable?: boolean;
+    }>;
+};
+export interface VoiceToolAddResponseResult {
+    ok: boolean;
+    toolName?: string;
+    toolOutput?: any;
+    message?: string;
+}
+/**
+ * One completed conversational turn during a voice session. Drives the
+ * chat-style transcript view. Live (in-flight) user/AI text is NOT in this
+ * list — see the live `transcript` / `userTranscript` strings on the hook
+ * result for the streaming/just-finished partial.
+ */
+export interface VoiceTranscriptTurn {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+}
+export type { ToolResponseMode } from '../components/Qafka.types';
+import type { ToolResponseMode } from '../components/Qafka.types';
+/**
+ * Resolve / preview a tool result.
+ *
+ * @param data Payload for UI (and AI when mode commits). Shape is
+ * consumer-defined; common pattern is `{ data: ... }`.
+ * @param tool The full tool object passed by `onToolSuggested`. The key is
+ * read from `tool.key`; no separate toolKey argument is needed.
+ * @param mode See {@link ToolResponseMode}. Defaults to `"both"`.
+ */
+export type VoiceToolAddResponse = (data: any, tool: any, mode?: ToolResponseMode) => Promise<VoiceToolAddResponseResult>;
+export type VoiceOnToolSuggested = (tools: any[], addResponse: VoiceToolAddResponse) => void | Promise<void>;
+/**
+ * Controls how renderedTools accumulates as new tool results stream in.
+ * - "upsert" (default): same toolKey replaces its previous entry; different
+ * toolKeys coexist on screen. Good for showing multiple unrelated cards.
+ * - "replace": every new tool result clears the previous renderedTools list,
+ * leaving only the latest single entry. Good for single-focus voice flows
+ * where a new tool means "switch the whole view".
+ */
+export type VoiceToolRenderMode = 'upsert' | 'replace';
+interface UseVoiceChatOptions {
+    apiUrl: string;
+    apiKey: string;
+    userContext?: Record<string, any>;
+    contextDescription?: string;
+    onToolSuggested?: VoiceOnToolSuggested;
+    toolRenderMode?: VoiceToolRenderMode;
+    /**
+    * Returns the current device-attestation session token, or null if no
+    * session has been established yet. Required in production: the server
+    * rejects WS connections without a valid session token.
+    */
+    getSessionToken?: () => Promise<string | null>;
+    /**
+     * Text/voice parity for the explicit end-user lane. Already validated
+     * by `<Qafka />` before reaching this hook.
+     */
+    endUserId?: string;
+    endUserData?: Record<string, unknown>;
+}
+interface UseVoiceChatResult {
+    state: VoiceChatState;
+    transcript: string;
+    userTranscript: string;
+    transcriptHistory: VoiceTranscriptTurn[];
+    amplitude: number;
+    connect: () => Promise<void>;
+    disconnect: () => Promise<void>;
+    pauseMic: () => Promise<void>;
+    resumeMic: () => Promise<void>;
+    isConnected: boolean;
+    toolStatus: VoiceToolStatus | null;
+    renderedTools: VoiceRenderedTool[];
+    transcriptOverrideForTurn: boolean;
+    clearRenderedTools: () => void;
+    setToolStatusManually: (status: {
+        toolKey: string;
+        loadingMessage: string;
+    } | null) => void;
+    /**
+     * User-controlled mute state. Independent from the internal tool-flow mute
+     * the hook applies during AI/tool transitions: even when system unmute
+     * fires, the mic stays off until the user clears their own mute.
+     */
+    isMuted: boolean;
+    mute: () => void;
+    unmute: () => void;
+    toggleMute: () => void;
+}
+export declare function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolSuggested, toolRenderMode, getSessionToken, endUserId, endUserData, }: UseVoiceChatOptions): UseVoiceChatResult;