@qafka/react-native 2.0.0

package/dist/QafkaSDK.js

@@ -0,0 +1,461 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSDK = exports.QafkaSDK = void 0;
+const storage_1 = require("./services/storage");
+const BackendService_1 = require("./services/BackendService");
+const AttestationManager_1 = require("./services/AttestationManager");
+const ConversationManager_1 = require("./services/ConversationManager");
+const NavigationHandler_1 = require("./services/NavigationHandler");
+/**
+ * QafkaSDK - Main SDK class
+ * Provides AI-powered conversational interface for React Native apps
+ */
+class QafkaSDK {
+    static instance = null;
+    config = null;
+    status = 'uninitialized';
+    subProjectId = null;
+    backendService = null;
+    attestationManager = null;
+    conversationManager = null;
+    navigationHandler = null;
+    // Theme fetch is fired during initialize() in parallel with attestation so
+    // ChatPage can render the branded greeting without waiting for SDK ready.
+    // See `useProjectTheme` which awaits this promise.
+    themePrefetchPromise = null;
+    constructor() { }
+    /**
+    * Get singleton instance
+    */
+    static getInstance() {
+        if (!QafkaSDK.instance) {
+            QafkaSDK.instance = new QafkaSDK();
+        }
+        return QafkaSDK.instance;
+    }
+    /**
+    * Initialize SDK
+    */
+    async initialize(config) {
+        if (this.status === 'ready') {
+            const currentApiKey = this.config?.apiKey ?? null;
+            const currentSubProjectId = this.subProjectId;
+            const newApiKey = config.apiKey ?? null;
+            const newSubProjectId = config.subProjectId ?? null;
+            if (currentApiKey === newApiKey && currentSubProjectId === newSubProjectId) {
+                return;
+            }
+            await this.destroy();
+        }
+        this.status = 'initializing';
+        this.config = config;
+        this.subProjectId = config.subProjectId ?? null;
+        try {
+            const apiKey = this.resolveApiKey(config);
+            // Initialize services synchronously BEFORE any `await` so that the
+            // theme-prefetch promise is observable on the next microtask. If this
+            // moves after an await, useProjectTheme (in the same render tick) sees
+            // `getThemePrefetch() === null` and falls back to the slow path.
+            this.backendService = new BackendService_1.BackendService(apiKey, config.apiUrl, this.subProjectId ?? undefined);
+            if (config.locale) {
+                this.backendService.setLocale(config.locale);
+            }
+            // Theme prefetch can only run synchronously here when there is an apiKey
+            // to authenticate the request. Without one, the credentials the request
+            // needs are not ready yet — firing the prefetch now would fail, blank out
+            // the greeting, and need a retry. Deferred to after init below.
+            if (apiKey) {
+                this.themePrefetchPromise = this.prefetchAndCacheTheme().catch(() => null);
+            }
+            // Save config to storage
+            await storage_1.storage.setItem('@qafka/config', JSON.stringify(config));
+            this.conversationManager = new ConversationManager_1.ConversationManager();
+            await this.conversationManager.initialize();
+            this.navigationHandler = new NavigationHandler_1.NavigationHandler(config.navigationRef);
+            // Initialize device attestation
+            const rawUrl = (config.apiUrl || 'https://api.qafka.com/api/v1').replace(/\/$/, '');
+            const attestApiUrl = rawUrl.includes('/api/v1') ? rawUrl : `${rawUrl}/api/v1`;
+            this.attestationManager = new AttestationManager_1.AttestationManager({
+                apiUrl: attestApiUrl,
+                apiKey: apiKey ?? null,
+                debug: config.debug,
+            });
+            try {
+                await this.attestationManager.initialize();
+                this.backendService.setAttestationManager(this.attestationManager);
+                this.backendService.setSessionTokenGetter(() => this.attestationManager.getSessionToken());
+                // Deferred theme prefetch — see the apiKey-gated branch above.
+                // Now that the session token getter is wired, the request carries the
+                // credentials it needs and the prefetch will succeed on first try,
+                // hydrating useProjectTheme before the chat surface paints.
+                if (!apiKey && !this.themePrefetchPromise) {
+                    this.themePrefetchPromise = this.prefetchAndCacheTheme().catch(() => null);
+                }
+            }
+            catch (error) {
+                // The unsupported-device fallback only applies on simulators/emulators.
+                // On real devices, attestation errors must propagate — even in __DEV__ —
+                // so that initialization cannot silently continue unverified.
+                if (this.attestationManager.isDevBypass()) {
+                    if (__DEV__) {
+                        console.warn('[Qafka] Attestation not supported on this device, continuing without it.');
+                    }
+                }
+                else {
+                    throw error;
+                }
+            }
+            this.status = 'ready';
+            if (config.onStatusChange) {
+                config.onStatusChange('ready');
+            }
+        }
+        catch (error) {
+            this.status = 'error';
+            if (config.onStatusChange) {
+                config.onStatusChange('error');
+            }
+            // In dev/debug mode, surface the full error for diagnostic value. In
+            // production builds, log only a generic marker so internal error
+            // messages do not leak. Integrators receive the categorised status
+            // via `onStatusChange('error')` regardless.
+            if (__DEV__ || config.debug) {
+                console.warn('[Qafka] Initialization failed:', error);
+            }
+            else {
+                console.warn('[Qafka] Initialization failed');
+            }
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to initialize QafkaSDK: ${detail}`);
+        }
+    }
+    /**
+    * developer-driven locale (BCP 47 — e.g. "tr", "en", "tr-TR").
+    * Forwarded to BackendService so it lands in `sdkContext.locale` on every
+    * outgoing chat request, which the server then echoes into the user-message
+    * context prefix. Same value should drive UI strings on the SDK side.
+    *
+    * Pass `null` to clear (e.g. when switching back to instructions-default).
+    * Calling before initialize() is a no-op; pass `locale` via SDKConfig instead.
+    */
+    setLocale(locale) {
+        this.backendService?.setLocale(locale);
+    }
+    /**
+     * Tool Data Channel: register the partner-provided resolver
+     * that supplies opaque PII bags for `{{tooldata.X}}` substitution on
+     * the backend. Called from `Qafka.tsx` whenever the `onToolDataRequested`
+     * prop changes. Pass `null` to clear.
+     */
+    setOnToolDataRequested(resolver) {
+        this.backendService?.setOnToolDataRequested(resolver);
+    }
+    /**
+    * Returns the current device-attestation session token (or `null` when
+    * attestation is unavailable). Voice mode passes this in the auth frame so
+    * the realtime WS opens against an attested session.
+    */
+    async getSessionToken() {
+        if (!this.attestationManager)
+            return null;
+        return this.attestationManager.getSessionToken();
+    }
+    /**
+     * Propagate the validated end-user identity from the React component
+     * into the transport layer. Called by `<Qafka />` in an effect whenever
+     * the `endUserId` / `endUserData` props change. Validation happens at
+     * the component boundary (`validate-end-user.ts`).
+     */
+    setEndUser(endUserId, endUserData) {
+        this.backendService?.setEndUser(endUserId, endUserData);
+    }
+    /**
+    * Send a chat message
+    */
+    async sendMessage(message, context, contextDescription, isInitialMessage) {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!message.trim()) {
+            throw new Error('Message cannot be empty');
+        }
+        try {
+            // Skip conversation manager for initial messages (no DB save, no local history)
+            if (!isInitialMessage) {
+                const userMessage = {
+                    id: this.generateId(),
+                    role: 'user',
+                    text: message,
+                    content: message,
+                    timestamp: new Date(),
+                };
+                this.conversationManager?.addMessage(userMessage);
+            }
+            // Send to backend
+            const sessionId = (await this.conversationManager?.getSessionId()) || this.generateId();
+            const response = await this.backendService.sendMessage(message, sessionId, context, contextDescription, isInitialMessage);
+            // Add to conversation (skip for initial messages)
+            if (!isInitialMessage) {
+                this.conversationManager?.addMessage({
+                    id: response.id,
+                    role: 'assistant',
+                    text: response.text || '',
+                    content: response.text || '',
+                    timestamp: response.timestamp,
+                    metadata: {},
+                });
+            }
+            // Handle navigation if suggested
+            if (response.navigationSuggestion && this.config?.onNavigationSuggest) {
+                this.config.onNavigationSuggest(response.navigationSuggestion);
+            }
+            return response;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    /**
+    * Send message with streaming response
+    */
+    async sendMessageStream(message, onChunk, onComplete, onError, context, contextDescription, onToolSuggestions, // Tool suggestions callback
+    isInitialMessage, onActionResult, // Action result callback
+    onStepCompleted, // Step completed callback
+    onFileUploadRequest, // File upload request callback
+    onExtractionResult, // Extraction result callback
+    // three new stream events
+    onToolStatus, onToolResultPayload, onFinalChunk) {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!message.trim()) {
+            throw new Error('Message cannot be empty');
+        }
+        try {
+            // Skip conversation manager for initial messages
+            if (!isInitialMessage) {
+                const userMessage = {
+                    id: this.generateId(),
+                    role: 'user',
+                    text: message,
+                    content: message,
+                    timestamp: new Date(),
+                };
+                this.conversationManager?.addMessage(userMessage);
+            }
+            // Skip local AI for streaming, always use backend
+            const sessionId = (await this.conversationManager?.getSessionId()) || this.generateId();
+            await this.backendService.sendMessageStream(message, sessionId, onChunk, (response) => {
+                // Add to conversation (skip for initial messages)
+                if (!isInitialMessage) {
+                    this.conversationManager?.addMessage({
+                        id: response.id,
+                        role: 'assistant',
+                        text: response.text || '',
+                        content: response.text || '',
+                        timestamp: response.timestamp,
+                        metadata: {},
+                    });
+                }
+                // Handle navigation if suggested
+                if (response.navigationSuggestion &&
+                    this.config?.onNavigationSuggest) {
+                    this.config.onNavigationSuggest(response.navigationSuggestion);
+                }
+                onComplete?.(response);
+            }, (_error) => {
+                onError?.(_error);
+            }, context, contextDescription, onToolSuggestions, // Pass tool suggestions callback
+            isInitialMessage, onActionResult, // Pass action result callback
+            onStepCompleted, // Pass step completed callback
+            onFileUploadRequest, // Pass file upload request callback
+            onExtractionResult, // Pass extraction result callback
+            onToolStatus, //
+            onToolResultPayload, //
+            onFinalChunk);
+        }
+        catch (error) {
+            if (onError) {
+                onError(error instanceof Error ? error : new Error('Unknown error'));
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    /**
+    * Get conversation history
+    */
+    async getConversationHistory() {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!this.conversationManager) {
+            throw new Error('Conversation manager not initialized');
+        }
+        return this.conversationManager.getHistory();
+    }
+    /**
+    * Clear conversation history
+    */
+    async clearConversation() {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!this.conversationManager) {
+            throw new Error('Conversation manager not initialized');
+        }
+        await this.conversationManager.clear();
+    }
+    /**
+    * Start a new conversation
+    * Clears history and returns the new session ID
+    */
+    async startNewConversation() {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!this.conversationManager) {
+            throw new Error('Conversation manager not initialized');
+        }
+        await this.conversationManager.clear();
+        return this.conversationManager.getSessionId();
+    }
+    /**
+    * Add tool response to conversation
+    * Use this after executing a tool to display the results
+    */
+    addToolResponse(toolKey, data, tool) {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!this.conversationManager) {
+            throw new Error('Conversation manager not initialized');
+        }
+        const message = {
+            id: this.generateId(),
+            role: 'assistant',
+            text: '', // Will be rendered by component
+            content: '',
+            timestamp: new Date(),
+            toolResponse: {
+                toolKey,
+                data,
+                tool,
+            },
+        };
+        this.conversationManager.addMessage(message);
+        return message;
+    }
+    /**
+    * Post a tool result back to the backend so the AI can continue its turn.
+    */
+    async postToolResult(payload, onFinalChunk, onDone, onError, onCard) {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!this.backendService) {
+            throw new Error('Backend service not initialized');
+        }
+        return this.backendService.postToolResult(payload, onFinalChunk, onDone, onError, onCard);
+    }
+    /**
+    * Upload a file attached to a tool flow.
+    */
+    async uploadFile(toolId, file, conversationId) {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        return this.backendService.uploadFile(toolId, file, conversationId);
+    }
+    /**
+    * Get project theme configuration
+    */
+    async getProjectTheme() {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!this.backendService) {
+            throw new Error('Backend service not initialized');
+        }
+        return this.backendService.getTheme();
+    }
+    /**
+    * Returns the in-flight theme prefetch (kicked off in initialize() parallel
+    * with attestation). Used by `useProjectTheme` to paint the branded greeting
+    * without waiting for `status === 'ready'`. Returns `null` if initialize()
+    * hasn't been called yet or if prefetch already settled.
+    */
+    getThemePrefetch() {
+        return this.themePrefetchPromise;
+    }
+    /**
+    * Fetches the project theme via BackendService and writes the result to
+    * persistent cache so subsequent chat opens paint instantly.
+    */
+    async prefetchAndCacheTheme() {
+        if (!this.backendService)
+            return null;
+        const themeData = await this.backendService.getTheme();
+        if (themeData) {
+            try {
+                const cacheKey = `@qafka/theme:${this.subProjectId ?? 'main'}`;
+                await storage_1.storage.setItem(cacheKey, JSON.stringify(themeData));
+            }
+            catch {
+                // Cache write failures are non-fatal — live theme is still in memory.
+            }
+        }
+        return themeData;
+    }
+    /**
+    * Get SDK status
+    */
+    getStatus() {
+        return this.status;
+    }
+    /**
+    * Get SDK configuration
+    */
+    getConfig() {
+        return this.config;
+    }
+    /**
+    * Navigate to screen
+    */
+    navigate(screenName, params) {
+        if (!this.navigationHandler) {
+            throw new Error('Navigation handler not initialized');
+        }
+        this.navigationHandler.navigate(screenName, params);
+    }
+    /**
+    * Generate unique ID
+    */
+    generateId() {
+        return `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+    * Resolve API key from config
+    */
+    resolveApiKey(config) {
+        return config.apiKey ?? null;
+    }
+    /**
+    * Destroy SDK instance
+    */
+    async destroy() {
+        this.backendService = null;
+        this.conversationManager = null;
+        this.navigationHandler = null;
+        this.subProjectId = null;
+        this.config = null;
+        this.themePrefetchPromise = null;
+        this.status = 'uninitialized';
+        QafkaSDK.instance = null;
+    }
+}
+exports.QafkaSDK = QafkaSDK;
+// Export singleton instance getter
+const getSDK = () => QafkaSDK.getInstance();
+exports.getSDK = getSDK;

package/dist/cards/bindings/resolveFieldName.d.ts

@@ -0,0 +1,25 @@
+import type { FieldName } from "../types";
+/**
+ * Resolves a fieldName string against a data object.
+ *
+ * Grammar:
+ * - Plain dot notation: `user.profile.name`
+ * - Leading dot ".": current iteration item (used inside QList itemTemplate later)
+ * - Returns `undefined` for missing paths; renderer skips-on-undefined for optional bindings.
+ */
+export declare function resolveFieldName(fieldName: FieldName | undefined, data: unknown, iterationItem?: unknown): unknown;
+/**
+ * Resolves `{{fieldName}}` placeholders inside a string template against data.
+ * Used for CTA params/labels where binding is embedded in a value, not a separate prop.
+ */
+export declare function resolveTemplateString(template: string, data: unknown, iterationItem?: unknown): string;
+/**
+ * Walks a value (string / object / array) and resolves any embedded `{{...}}` templates.
+ * Used for CTA action configs where params object may contain templates at any depth.
+ */
+export declare function resolveDeep<T>(value: T, data: unknown, iterationItem?: unknown): T;
+/**
+ * Truthiness check for `showIf` bindings — string "false"/"0"/"" are treated as false,
+ * matching common JSON serialization edge cases.
+ */
+export declare function evaluateShowIf(showIf: FieldName | undefined, data: unknown, iterationItem?: unknown): boolean;

package/dist/cards/bindings/resolveFieldName.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFieldName = resolveFieldName;
+exports.resolveTemplateString = resolveTemplateString;
+exports.resolveDeep = resolveDeep;
+exports.evaluateShowIf = evaluateShowIf;
+/**
+ * Resolves a fieldName string against a data object.
+ *
+ * Grammar:
+ * - Plain dot notation: `user.profile.name`
+ * - Leading dot ".": current iteration item (used inside QList itemTemplate later)
+ * - Returns `undefined` for missing paths; renderer skips-on-undefined for optional bindings.
+ */
+function resolveFieldName(fieldName, data, iterationItem) {
+    if (!fieldName)
+        return undefined;
+    const usesIteration = fieldName.startsWith(".");
+    const target = usesIteration ? iterationItem : data;
+    const path = usesIteration ? fieldName.slice(1) : fieldName;
+    if (target == null)
+        return undefined;
+    if (path === "")
+        return target;
+    return path.split(".").reduce((acc, segment) => {
+        if (acc == null || typeof acc !== "object")
+            return undefined;
+        return acc[segment];
+    }, target);
+}
+/**
+ * Resolves `{{fieldName}}` placeholders inside a string template against data.
+ * Used for CTA params/labels where binding is embedded in a value, not a separate prop.
+ */
+function resolveTemplateString(template, data, iterationItem) {
+    return template.replace(/\{\{([^}]+)\}\}/g, (_, expr) => {
+        const trimmed = expr.trim();
+        const value = resolveFieldName(trimmed, data, iterationItem);
+        return value == null ? "" : String(value);
+    });
+}
+/**
+ * Walks a value (string / object / array) and resolves any embedded `{{...}}` templates.
+ * Used for CTA action configs where params object may contain templates at any depth.
+ */
+function resolveDeep(value, data, iterationItem) {
+    if (typeof value === "string") {
+        return resolveTemplateString(value, data, iterationItem);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => resolveDeep(v, data, iterationItem));
+    }
+    if (value != null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = resolveDeep(v, data, iterationItem);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Truthiness check for `showIf` bindings — string "false"/"0"/"" are treated as false,
+ * matching common JSON serialization edge cases.
+ */
+function evaluateShowIf(showIf, data, iterationItem) {
+    if (showIf === undefined)
+        return true;
+    const value = resolveFieldName(showIf, data, iterationItem);
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === "string") {
+        const normalized = value.toLowerCase().trim();
+        if (normalized === "" || normalized === "false" || normalized === "0")
+            return false;
+    }
+    if (typeof value === "number")
+        return value !== 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    return Boolean(value);
+}

package/dist/cards/cta/CardContext.d.ts

@@ -0,0 +1,16 @@
+import React from "react";
+import type { CardCTAHostCallbacks, CardCTALifecycle } from "./types";
+export interface CardRuntimeContextValue {
+    data: unknown;
+    cardTemplateId: string;
+    cardSlug: string;
+    messageId?: string;
+    hostCallbacks: CardCTAHostCallbacks;
+    lifecycle: CardCTALifecycle;
+    dismiss: () => void;
+}
+export declare function CardRuntimeProvider({ value, children, }: {
+    value: CardRuntimeContextValue;
+    children: React.ReactNode;
+}): React.ReactElement;
+export declare function useCardRuntime(): CardRuntimeContextValue;

package/dist/cards/cta/CardContext.js

@@ -0,0 +1,58 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CardRuntimeProvider = CardRuntimeProvider;
+exports.useCardRuntime = useCardRuntime;
+const react_1 = __importStar(require("react"));
+const CardRuntimeContext = (0, react_1.createContext)(null);
+function CardRuntimeProvider({ value, children, }) {
+    const memo = (0, react_1.useMemo)(() => value, [
+        value.data,
+        value.cardTemplateId,
+        value.cardSlug,
+        value.messageId,
+        value.hostCallbacks,
+        value.lifecycle,
+        value.dismiss,
+    ]);
+    return (<CardRuntimeContext.Provider value={memo}>{children}</CardRuntimeContext.Provider>);
+}
+function useCardRuntime() {
+    const ctx = (0, react_1.useContext)(CardRuntimeContext);
+    if (!ctx) {
+        throw new Error("useCardRuntime must be used inside CardRuntimeProvider");
+    }
+    return ctx;
+}

package/dist/cards/cta/dispatcher.d.ts

@@ -0,0 +1,7 @@
+import type { CTADispatcher } from "./types";
+/**
+ * SDK-internal CTA dispatcher.
+ * Resolves embedded `{{fieldName}}` templates against the card's data context at click time.
+ * Falls back to host callbacks for actions that cross the SDK boundary (deep_link, tool_trigger).
+ */
+export declare const dispatchCTA: CTADispatcher;