@qafka/react-native 2.0.0

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

@@ -0,0 +1,744 @@
+import { ViewStyle } from 'react-native';
+import { Theme, ThemeOverride } from '../themes';
+import { ComponentRegistry } from '../types/components';
+import { ExternalSuggestion } from '../types/external-navigation';
+import { NavigationSuggestion } from '../types/navigation';
+import { VoiceChatState } from './VoicePage';
+/**
+ * Augmentation hook for consumer-side projectId literal types.
+ *
+ * The Qafka CLI generates a `qafka.config.d.ts` file alongside
+ * `qafka.config.js` whenever it writes the runtime config. That `.d.ts`
+ * augments this interface with the consumer's project ids as keys —
+ * giving `<Qafka projectId="..." />` autocomplete + typo validation.
+ *
+ * When the augmentation is absent (fresh project, `qafka init` not yet
+ * run), `keyof QafkaProjectIds` is `never` and `ProjectIdOf` falls back
+ * to plain `string` for backwards compatibility.
+ *
+ * Consumers don't interact with this interface directly — the CLI manages it.
+ */
+export interface QafkaProjectIds {
+}
+/**
+ * Resolves to the consumer's registered project ids (literal union) when
+ * the CLI-generated `qafka.config.d.ts` has populated `QafkaProjectIds`,
+ * or to `string` otherwise.
+ */
+export type ProjectIdOf = [keyof QafkaProjectIds] extends [never] ? string : keyof QafkaProjectIds;
+/**
+ * Controls what `addResponse` does inside an `onToolSuggested` handler.
+ * Same semantics in both voice and text chat.
+ *
+ * - `"ui"`: Only update the rendered tool UI / chat card. Does NOT close the
+ *   tool flow. Use for progress updates, optimistic state, or partial render
+ *   before the real result arrives. You MUST eventually call `addResponse`
+ *   again with `"both"` or `"data"` to close the tool out.
+ * - `"data"`: Commit the tool flow without touching the UI.
+ * - `"both"` (default): UI render + commit.
+ */
+export type ToolResponseMode = 'ui' | 'data' | 'both';
+/**
+ * Props passed to custom voice indicator component.
+ *
+ * `isMuted` reflects the user's manual mute toggle, not the internal
+ * tool-flow mute. Use it to dim or otherwise mark the indicator while the
+ * user has the mic off.
+ */
+export interface VoiceIndicatorProps {
+    state: VoiceChatState;
+    amplitude: number;
+    theme: Theme;
+    isMuted?: boolean;
+}
+/**
+ * Props passed to a custom voice mute button. Same shape across all three
+ * VoicePage layouts (centered orb, chat layout, compact tool bar); the
+ * layout decides where to place it, the component only renders the control.
+ */
+export interface VoiceMuteButtonProps {
+    isMuted: boolean;
+    onToggle: () => void;
+    theme: Theme;
+    state: VoiceChatState;
+}
+/**
+ * Props passed to custom voice background component
+ */
+export interface VoiceBackgroundProps {
+    state: VoiceChatState;
+    amplitude: number;
+    theme: Theme;
+    children: React.ReactNode;
+}
+/**
+ * One completed conversational turn captured during a voice session. Live
+ * (still-streaming) AI text and just-finalized-but-not-yet-pushed user text
+ * are NOT in here — those are still on `transcript` / `userTranscript`.
+ */
+export interface VoiceTranscriptTurn {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+}
+/**
+ * Render mode for the voice transcript area.
+ *
+ * - `"centered"`: a single line of the current AI transcript centered above
+ *   the state label. Minimal vertical footprint. No history.
+ * - `"chat"`: scrolling chat history of both user and AI turns, lightweight
+ *   (no bubble backgrounds, role-aligned, older turns fade) so it stays
+ *   visually distinct from text mode. While a tool is rendered on screen,
+ *   the chat collapses automatically — the compact status bar takes over,
+ *   and the chat reappears when the tool UI is dismissed.
+ * - `"off"`: transcripts and state label hidden. Only the orb is visible.
+ */
+export type VoiceTranscriptMode = 'off' | 'centered' | 'chat';
+/**
+ * Props passed to custom voice transcript component.
+ *
+ * `history` and `mode` are only populated when the consumer opts into
+ * `voiceTranscript="chat"`. For the default `"centered"` mode, the custom
+ * component should rely on the live `transcript` string only.
+ */
+export interface VoiceTranscriptProps {
+    transcript: string;
+    userTranscript: string;
+    state: VoiceChatState;
+    theme: Theme;
+    mode?: VoiceTranscriptMode;
+    history?: VoiceTranscriptTurn[];
+}
+/**
+ * Custom voice components registry
+ * Allows customers to provide their own Lottie, GIF, Image, or any React component
+ * for the voice chat UI. If not provided, defaults are used.
+ */
+export interface VoiceComponents {
+    VoiceIndicator?: React.ComponentType<VoiceIndicatorProps>;
+    VoiceBackground?: React.ComponentType<VoiceBackgroundProps>;
+    VoiceTranscript?: React.ComponentType<VoiceTranscriptProps>;
+    /**
+     * Slot for the manual mute toggle rendered on the right side of the orb
+     * row in every voice layout. Defaults to a circular icon button.
+     */
+    VoiceMuteButton?: React.ComponentType<VoiceMuteButtonProps>;
+    /**
+     * Slot for the multi-chip list rendered when the AI calls the built-in
+     * `qafka_display` tool with mode="chip".
+     */
+    dataChipList?: React.ComponentType<{
+        items: Array<{
+            label: string;
+            value: string;
+            copyable?: boolean;
+        }>;
+        theme?: any;
+    }>;
+    /**
+     * Slot for an individual chip used inside the default DataChipList.
+     */
+    dataChip?: React.ComponentType<{
+        label: string;
+        value: string;
+        copyable?: boolean;
+        theme?: any;
+    }>;
+}
+/**
+ * Imperative handle returned by Qafka via `ref`.
+ *
+ * Use when your custom logic has async work outside of `onToolSuggested`
+ * (e.g. the developer is driving a multi-step flow manually).
+ *
+ * @example
+ * const qafkaRef = useRef<QafkaHandle>(null);
+ * qafkaRef.current?.setLoading(true, 'Fetching data...');
+ * // ...do work...
+ * qafkaRef.current?.setLoading(false);
+ *
+ * <Qafka ref={qafkaRef} />
+ */
+export interface QafkaHandle {
+    /**
+    * Manually control the voice-mode loading pill + mic pause state.
+    * Use when your custom logic has async work outside of onToolSuggested.
+    *
+    * @param visible - true to show pill + pause mic, false to hide + resume
+    * @param message - optional pill text. Defaults to "Processing…" when omitted.
+    */
+    setLoading(visible: boolean, message?: string): void;
+    /**
+    * Clear all currently rendered voice tool UI cards. Useful when starting
+    * a fresh interaction or when the consumer wants to reset the view
+    * outside of the tool-result flow.
+    */
+    clearRenderedTools(): void;
+    /**
+    * Send a text message to the AI as if the user typed it. Triggers the
+    * normal message-send pipeline — streaming reply, tool suggestions, etc.
+    * Useful for quick-reply buttons, deep links, or programmatic prompts.
+    */
+    sendMessage(text: string): void;
+    /**
+    * Open the realtime voice session programmatically. Same as the user
+    * tapping the mic button.
+    */
+    connectVoice(): Promise<void>;
+    /**
+    * Close the realtime voice session programmatically. Safe to call when
+    * already disconnected (no-op).
+    */
+    disconnectVoice(): Promise<void>;
+    /**
+    * Pause microphone capture without ending the voice session. The AI keeps
+    * speaking, the user just cannot be heard until {@link resumeMic} is
+    * called. Useful for push-to-talk patterns or letting the user mute
+    * temporarily.
+    */
+    pauseMic(): Promise<void>;
+    /**
+    * Resume microphone capture after a {@link pauseMic} call. Idempotent —
+    * safe to call when the mic is already active.
+    */
+    resumeMic(): Promise<void>;
+    /**
+     * Manually toggle the user-controlled mute. Independent from the internal
+     * tool-flow mute the SDK applies during AI / tool transitions — user mute
+     * persists across those, matching Teams/Zoom semantics.
+     */
+    toggleMute(): void;
+    /**
+     * Engage the user mute. Idempotent.
+     */
+    mute(): void;
+    /**
+     * Lift the user mute. Idempotent. If a tool flow is currently muting the
+     * mic internally, the mic stays off until that flow completes.
+     */
+    unmute(): void;
+    /**
+     * Whether the user has the mic muted right now. Reflects the user toggle
+     * only, not the internal tool-flow mute.
+     */
+    readonly isMuted: boolean;
+}
+/**
+ * Props for Qafka Component
+ *
+ * @example
+ * // Basic usage
+ * <Qafka projectId="proj_abc123" />
+ */
+export interface QafkaProps {
+    style?: ViewStyle;
+    /**
+     * Project identifier when the runtime config registers more than one
+     * project. Selects which project's development key the SDK uses in
+     * development builds (loaded from `qafka.config.js`).
+     *
+     * Leave undefined to use the runtime config's default project. Pass a
+     * project id that is unknown to the runtime config and the SDK throws on
+     * mount — silent fallback would mask a typo.
+     *
+     * In production builds this prop is ignored by the key-resolution path,
+     * which does not rely on a bundled key.
+     *
+     * When the Qafka CLI has been run (`qafka init` / `qafka project` /
+     * `qafka sync`), this prop is narrowed to the registered project ids —
+     * giving autocomplete and typo validation. Without the CLI augmentation
+     * the type falls back to `string` for backwards compatibility.
+     *
+     * @example "proj_abc123"
+     */
+    projectId?: ProjectIdOf;
+    /**
+    * Backend API URL (OPTIONAL — advanced, leave unset for production).
+    */
+    apiUrl?: string;
+    /**
+    * Sub-Project Identifier (OPTIONAL)
+    *
+    * Used for multi-tenant setups where a single project serves multiple
+    * sub-projects (e.g., per-region or per-tenant rollouts).
+    *
+    * When provided, sub-project routing is applied server-side.
+    * If omitted, the parent project is used directly (backward compatible).
+    *
+    * @example "tenant-a"
+    */
+    subProjectId?: string;
+    /**
+    * BCP 47 locale (e.g. "tr", "en", "tr-TR").
+    *
+    * Drives UI strings (placeholder, buttons, dashboard-supplied multi-locale
+    * greeting) and is forwarded to the backend as part of `sdkContext.locale`.
+    * Pair with the server-side language priority rule: when set, the AI
+    * answers in this locale unless project instructions explicitly demand
+    * another language.
+    *
+    * Leave undefined to fall back to whatever language the project
+    * instructions are written in.
+    *
+    * @example "tr"
+    * @example "en-US"
+    */
+    locale?: string;
+    /**
+    * Widget display mode
+    */
+    mode?: 'fullscreen' | 'inline' | 'floating';
+    /**
+    * Theme mode or custom theme object
+    */
+    theme?: 'light' | 'dark' | Theme;
+    /**
+    * Theme overrides (partial theme)
+    * Allows overriding specific theme properties without replacing the entire theme
+    * @example { colors: { background: '#FF0000' } }
+    */
+    themeOverride?: ThemeOverride;
+    /**
+    * Full custom theme that replaces the default theme entirely. Pair this with
+    * `themeOverride` only when you need to merge partial overrides on top.
+    */
+    customTheme?: Theme;
+    /**
+    * Enable streaming responses (real-time typing effect)
+    */
+    enableStreaming?: boolean;
+    /**
+    * Whether the current user is authenticated.
+    * Controls which screens are suggested in navigation:
+    * - true: authenticated screens suggested, unauthenticated screens hidden
+    * - false: unauthenticated screens suggested, authenticated screens hidden
+    * - undefined: backward compatible behavior (all screens suggested)
+    *
+    * @example isAuthenticated={!!user}
+    */
+    isAuthenticated?: boolean;
+    /**
+     * Stable identifier for the end user using this SDK instance.
+     *
+     * Required. The backend uses this id to group conversations, action logs,
+     * and audience analytics per user. Send a constant placeholder
+     * (`"anonymous"`, `"anon-${deviceId}"`, ...) before the user signs in so
+     * pre-login activity still has a stable lane.
+     *
+     * The value is validated on mount and on every chat request:
+     *   - empty / null / whitespace → runtime Error
+     *   - longer than 256 characters → runtime Error
+     *
+     * Numbers are accepted and coerced to string before they leave the SDK.
+     *
+     * NOT forwarded to the LLM prompt — operator dashboards and tool action
+     * templates can reach it via `{{endUser.id}}` without leaking it to the AI.
+     *
+     * @example endUserId={user?.id ?? `anon-${deviceId}`}
+     */
+    endUserId: string | number;
+    /**
+     * Optional structured profile data for operator dashboards and tool
+     * action templates (`{{endUser.data.<key>}}`).
+     *
+     * NEVER forwarded to the LLM prompt. If you want the AI to see something,
+     * put it in `context` instead.
+     *
+     * Limited to 8KB when serialized to JSON; exceeding the limit causes the
+     * field to be dropped from the request (with a `console.error`) — chat
+     * and tracking continue to work.
+     *
+     * @example endUserData={{ email: 'user@example.com', plan: 'pro' }}
+     */
+    endUserData?: Record<string, unknown>;
+    /**
+    * Context object for Tool Registry.
+    * Provides runtime context to match and execute tools.
+    * @example { userId: '456', selectedItemId: '123' }
+    */
+    context?: Record<string, any>;
+    /**
+    * Context description for the AI.
+    * Helps the AI understand what the context keys mean.
+    * @example "User is on the settings screen"
+    */
+    contextDescription?: string;
+    /**
+    * Custom component registry for Tool Registry responses.
+    * Register your own components to render tool responses.
+    * @example { ProductCard: MyProductCard, OrderCard: MyOrderCard }
+    */
+    components?: ComponentRegistry;
+    /**
+    * Show timestamps on messages
+    */
+    showTimestamps?: boolean;
+    /**
+    * Input placeholder text
+    */
+    placeholder?: string;
+    /**
+    * Header title
+    */
+    title?: string;
+    /**
+    * Show header
+    */
+    showHeader?: boolean;
+    /**
+    * Maximum message length
+    */
+    maxMessageLength?: number;
+    /**
+    * Custom users greeting message (overrides Project API greeting)
+    */
+    greetingMessage?: string;
+    /**
+    * Callback when widget is ready
+    */
+    onReady?: () => void;
+    /**
+    * Callback when message is sent
+    */
+    onMessageSent?: (message: string) => void;
+    /**
+    * Callback when response is received
+    */
+    onResponseReceived?: (response: any) => void;
+    /**
+    * Callback on error
+    */
+    onError?: (error: Error) => void;
+    /**
+    * Callback when navigation is suggested (always triggered)
+    */
+    onNavigationSuggest?: (suggestion: NavigationSuggestion) => void;
+    /**
+    * Callback when navigation button is pressed by user.
+    * If not provided, SDK automatically navigates using `suggestion.route` via Expo Router.
+    */
+    onNavigationAction?: (suggestion: NavigationSuggestion) => void;
+    /**
+    * Callback when an external suggestion button is pressed by user
+    * (WhatsApp, phone, map, app store, etc.).
+    *
+    * If not provided, the SDK opens the suggestion's `url` via
+    * `Linking.openURL`, falling back to `fallbackUrl` when the primary URL
+    * is not handleable on the device (e.g. the target app isn't installed).
+    *
+    * @example
+    * onExternalSuggestion={(s) => {
+    * analytics.track('external_nav_press', { type: s.type, id: s.id });
+    * Linking.openURL(s.url);
+    * }}
+    */
+    onExternalSuggestion?: (suggestion: ExternalSuggestion) => void;
+    /**
+    * Card Template CTA host callbacks. Invoked when a button
+    * inside a rendered card fires an action that crosses the SDK boundary
+    * (deep_link, share, suggest_message, copy, external_navigation, tool_trigger).
+    *
+    * The most common one is `onCardDeepLink` — partner navigates to an internal
+    * route from a card button:
+    *
+    * @example
+    * onCardDeepLink={(path) => router.push(path)}
+    *
+    * `copy` and `share` have sensible RN defaults (Clipboard / Share.share),
+    * so partners only register them when they want custom behavior (e.g.
+    * show a toast on copy success).
+    */
+    onCardDeepLink?: (path: string, action?: any) => void | Promise<void>;
+    onCardSuggestMessage?: (text: string) => void | Promise<void>;
+    onCardExternalNavigation?: (action: any) => void | Promise<void>;
+    onCardShare?: (payload: {
+        text?: string;
+        url?: string;
+    }) => void | Promise<void>;
+    onCardCopy?: (value: string) => void | Promise<void>;
+    /**
+    * Invoked when a card button has type "tool_trigger". The host can
+    * forward this to the SDK's tool execution path or surface it as a new
+    * chat message. Optional; if unset the action is silently skipped.
+    */
+    onCardToolTrigger?: (toolName: string, params: Record<string, unknown>, meta: {
+        ctaDisplayMode: 'user_message' | 'silent';
+    }) => void | Promise<void>;
+    /**
+    * CTA telemetry hook — called once per click. The event payload mirrors
+    * `CardCTATelemetryEvent` from the cards module:
+    * - `item` carries the bound record (the iterated item in list mode,
+    * full tool result in detail mode), so partners don't have to look
+    * it up by index.
+    * - `itemIndex` is present only in list mode.
+    */
+    onCardCTAClick?: (event: {
+        event: 'cta_click';
+        cardTemplateId: string;
+        cardSlug: string;
+        actionType: string;
+        toolName?: string;
+        messageId?: string;
+        itemIndex?: number;
+        item: unknown;
+        confirmed: boolean;
+    }) => void;
+    /**
+    * Callback when Tool Registry suggests tools
+    * Called during streaming when backend identifies matching tools
+    * @param tools - Array of matched tool definitions with relevance scores and customData
+    * @param addResponse - Helper function to add tool response to chat
+    * @example
+    * onToolSuggested={async (tools, addResponse) => {
+    * const tool = tools[0];
+    * // tool.customData contains any custom data you attached to this tool
+    * const response = await fetch(tool.customData.apiBaseUrl + tool.endpoint);
+    * addResponse(tool.key, await response.json(), tool);
+    * }}
+    */
+    onToolSuggested?: (tools: any[], addResponse: (data: any, tool: any, mode?: ToolResponseMode) => void) => void | Promise<void>;
+    /**
+    * Callback when backend action execution results arrive
+    * Called during streaming when the backend sends action_result SSE events
+    * @param results - Array of action execution results
+    * @example
+    * onActionResult={(results) => {
+    * results.forEach(r => {
+    * if (r.success) Toast.show(r.message);
+    * });
+    * }}
+    */
+    onActionResult?: (results: Array<{
+        actionType: string;
+        success: boolean;
+        message: string;
+    }>) => void;
+    /**
+    * Tool Data Channel — partner-provided resolver for transient PII bags.
+    *
+    * Partner-provided resolver invoked when a suggested tool references
+    * `{{tooldata.X}}` tokens in its email/webhook body. Returned values are
+    * POSTed to backend's request-scoped cache and substituted into action
+    * payloads — **never sent to the LLM, never written to the Qafka DB**.
+    *
+    * Backend signals the need via `needData: true` on the `tool_suggestions`
+    * SSE event. SDK calls this resolver, POSTs the resulting opaque bag to
+    * `/chat/tool-data`, backend looks it up by `toolExecutionId` when running
+    * the tool's actions (email/webhook).
+    *
+    * Resolver may be sync or async. Throwing or rejecting is fail-soft —
+    * SDK posts an empty bag and `{{tooldata.X}}` tokens resolve to empty
+    * strings on the server, allowing the action to still run (just without
+    * the substituted PII).
+    *
+    * @param tool Suggested tool descriptor (key + name).
+    * @returns Plain object of key → string/number/boolean values, OR a
+    *   Promise of the same.
+    * @example
+    * onToolDataRequested={async ({ key }) => {
+    *   if (key === 'sendInvoice') {
+    *     const user = await store.getCurrentUser();
+    *     return { gsm: user.phone, email: user.email };
+    *   }
+    *   return {};
+    * }}
+    */
+    onToolDataRequested?: (tool: {
+        key: string;
+        name: string;
+    }) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /** Called when a step side-effect completes during a multi-step tool flow */
+    onStepCompleted?: (result: {
+        tool: string;
+        step: string;
+        data: Record<string, any>;
+        actionResults?: Array<{
+            actionType: string;
+            success: boolean;
+            message: string;
+        }>;
+    }) => void;
+    /**
+    * Called when a tool requires file upload from the user.
+    * The app should open its own file picker and call submit() with the selected file.
+    *
+    * @example
+    * onFileUploadRequest={({ toolId, fileInput, submit, cancel }) => {
+    * ImagePicker.launchImageLibrary({ mediaType: 'photo' }, (response) => {
+    * if (response.assets?.[0]) {
+    * submit({
+    * uri: response.assets[0].uri!,
+    * name: response.assets[0].fileName!,
+    * type: response.assets[0].type!,
+    * });
+    * } else {
+    * cancel();
+    * }
+    * });
+    * }}
+    */
+    onFileUploadRequest?: (request: {
+        toolId: string;
+        fileInput: {
+            accept: string[];
+            maxSize: number;
+            sources: string[];
+        };
+        submit: (file: {
+            uri: string;
+            name: string;
+            type: string;
+        }) => void;
+        cancel: () => void;
+    }) => void;
+    /**
+    * Called when document extraction completes after file upload.
+    * Contains the structured data extracted by AI from the uploaded document.
+    *
+    * @example
+    * onExtractionResult={({ toolId, data, status }) => {
+    * if (status === 'success') {
+    * setFormFields(data);
+    * }
+    * }}
+    */
+    onExtractionResult?: (result: {
+        fileId: string;
+        toolId: string;
+        data: Record<string, any>;
+        status: 'success' | 'partial' | 'failed';
+        incompleteFields?: string[];
+    }) => void;
+    /** Opt-out of voice chat. Server must also allow it. Default: true */
+    voiceEnabled?: boolean;
+    /**
+    * Custom voice page components
+    * Override the default voice indicator, background, or transcript components
+    * with your own (e.g. Lottie animation, GIF, custom visuals).
+    *
+    * @example
+    * voiceComponents={{
+    * VoiceIndicator: ({ state, amplitude, theme }) => (
+    * <LottieView source={lottieFile} speed={amplitude} />
+    * ),
+    * }}
+    */
+    voiceComponents?: VoiceComponents;
+    /**
+    * How the voice mode transcript area is displayed.
+    *
+    * - `"centered"` (default): single line of the current AI transcript above
+    *   the state label. Backward-compatible with prior SDK versions.
+    * - `"chat"`: scrolling history of user + AI turns. Hands-free friendly:
+    *   the chat collapses automatically when a tool result is rendered, and
+    *   resumes when the tool UI is dismissed.
+    * - `"off"`: hide transcripts and state label entirely; only the orb shows.
+    *
+    * @default "centered"
+    */
+    voiceTranscript?: VoiceTranscriptMode;
+    /**
+    * Controls how voice tool results accumulate on screen.
+    *
+    * - `"upsert"` (default): same toolKey replaces its previous entry; results
+    * from different tools coexist (e.g. `show_results` + `show_details`
+    * stack vertically). Best for browsing scenarios.
+    * - `"replace"`: every new tool result clears previous entries — only the
+    * latest single tool stays visible. Best for single-focus voice flows
+    * where switching tools means switching the whole view.
+    *
+    * @default "upsert"
+    */
+    toolRenderMode?: 'upsert' | 'replace';
+    /**
+    * Callback when close button is pressed
+    * If provided, a close button will be shown in the top right corner
+    */
+    onClose?: () => void;
+    /**
+    * Callback when back button is pressed
+    * If provided, a back button will be shown in the top left corner
+    */
+    onBack?: () => void;
+    /**
+    * Custom Close Component
+    * Overrides default close button
+    */
+    CloseComponent?: React.ComponentType<any>;
+    /**
+    * Custom Back Component
+    * Overrides default back button
+    */
+    BackComponent?: React.ComponentType<any>;
+    /**
+    * Navigation button label format function
+    * Allows customizing the navigation button text format
+    * Receives the screen name and returns the formatted label
+    *
+    * @example
+    * // Custom format: "Navigate to Profile"
+    * navigationLabelFormat={(screenName) => `Navigate to ${screenName}`}
+    *
+    * @example
+    * // Custom format: "Target screen: Profile"
+    * navigationLabelFormat={(screenName) => `Target screen: ${screenName}`}
+    */
+    navigationLabelFormat?: (screenName: string) => string;
+    /**
+    * Custom Navigation Button Component
+    * Overrides the default navigation button
+    * Receives the navigation suggestion data as props
+    *
+    * @example
+    * NavigationButtonComponent={({ screenName, onPress, style }) => (
+    * <TouchableOpacity onPress={onPress} style={yourCustomStyle}>
+    * <Text>Go to {screenName}</Text>
+    * </TouchableOpacity>
+    * )}
+    */
+    NavigationButtonComponent?: React.ComponentType<NavigationButtonProps>;
+}
+/**
+ * Props for custom NavigationButtonComponent
+ */
+export interface NavigationButtonProps {
+    /**
+    * The suggested screen name to navigate to
+    */
+    screenName: string;
+    /**
+    * Full navigation suggestion data from the backend
+    */
+    suggestion: NavigationSuggestion;
+    /**
+    * Callback when button is pressed
+    */
+    onPress: () => void;
+    /**
+    * Current theme
+    */
+    theme: Theme;
+    /**
+    * Button style variant
+    */
+    style?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning';
+    /**
+    * The formatted label text (already formatted by navigationLabelFormat or default)
+    */
+    label: string;
+    /**
+    * Optional icon for the button
+    */
+    icon?: string;
+}
+/**
+ * Action button type
+ */
+export interface ActionButton {
+    id: string;
+    type: 'navigation' | 'custom';
+    label: string;
+    icon?: string;
+    data: any;
+    style?: 'primary' | 'secondary' | 'success' | 'danger' | 'warning';
+}