@qafka/react-native 2.7.0 → 2.8.1

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [2.8.1] — 2026-10-06
+
+### Added
+
+- Close button on the voice page, in its top left corner. It only leaves voice: the voice session is ended and the widget returns to the chat page, so users no longer have to swipe back. The chat stays open and `onClose` is not called — closing the assistant is still done from the chat page.
+- New optional `onVoiceClose` prop on `<Qafka />`, called when that button is pressed.
+- New optional `voiceComponents.VoiceCloseButton` slot (`VoiceCloseButtonProps`) to replace the default button.
+
+## [2.8.0] — 2026-10-06
+
+### Added
+
+- Unavailable state now also covers a project for which the mobile SDK is not enabled: the chat screen shows the same neutral, localized message as for a suspended project, `onUnavailable` is called and the status becomes `'unavailable'` (via `onStatusChange` and `QafkaSDK.getStatus()`). No error bubble is shown and `onError` is not called. A voice session rejected for the same reason ends the same way.
+- New exported `FeatureNotAvailableError` (`code: 'FEATURE_NOT_AVAILABLE'`, with the `feature` name). SDK calls that fail because a feature is not enabled for the project reject with it, so you can tell this case apart from other failures. A feature other than the mobile SDK itself does not switch the SDK to the unavailable state — only that call fails.
+- In development builds, the SDK logs a one-time console warning naming the feature that is not enabled. Production builds log nothing.
+
+### Fixed
+
+- Voice could not be continued after returning to the voice page: when a voice session ended while the voice page stayed on screen (the assistant opened another screen and you came back, the app went to the background, or the connection dropped), the page stayed idle and only swiping to the text chat and back re-opened it. The voice page now shows "Tap to continue" (Turkish when `locale` starts with `tr`), and tapping the microphone button or the indicator re-opens the session. No public API changes.
+
 ## [2.7.0] — 2026-09-16
 
 ### Added

package/dist/QafkaSDK.js

@@ -4,6 +4,7 @@ exports.getSDK = exports.QafkaSDK = void 0;
 const storage_1 = require("./services/storage");
 const BackendService_1 = require("./services/BackendService");
 const projectUnavailable_1 = require("./services/projectUnavailable");
+const featureNotAvailable_1 = require("./services/featureNotAvailable");
 const AttestationManager_1 = require("./services/AttestationManager");
 const ConversationManager_1 = require("./services/ConversationManager");
 const NavigationHandler_1 = require("./services/NavigationHandler");
@@ -119,6 +120,21 @@ class QafkaSDK {
                 }
             }
             catch (error) {
+                // Any plan-gated feature warns the integrator once in __DEV__, but only
+                // mobile_sdk — the feature that gates the whole SDK — flips status to
+                // the neutral 'unavailable' UX. A different gated feature (e.g.
+                // card_templates) falls through to the normal error/dev-bypass handling
+                // below instead of taking down the rest of the SDK.
+                if (error instanceof featureNotAvailable_1.FeatureNotAvailableError) {
+                    (0, featureNotAvailable_1.warnFeatureNotAvailable)(error.feature);
+                    if ((0, featureNotAvailable_1.isMobileSdkDenied)(error)) {
+                        this.status = 'unavailable';
+                        if (config.onStatusChange) {
+                            config.onStatusChange('unavailable');
+                        }
+                        return;
+                    }
+                }
                 // 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.
@@ -132,16 +148,22 @@ class QafkaSDK {
                 }
             }
             // Decide the final status after the theme prefetch settles — a
-            // ProjectUnavailableError there means the project is suspended, which
-            // takes priority over an otherwise-successful attestation. This never
-            // rejects: the prefetch promise already swallows its own rejection
-            // (see themePrefetchError above).
+            // ProjectUnavailableError / FeatureNotAvailableError there means the
+            // project is suspended or plan-gated, which takes priority over an
+            // otherwise-successful attestation. This never rejects: the prefetch
+            // promise already swallows its own rejection (see themePrefetchError
+            // above).
             if (this.themePrefetchPromise) {
                 await this.themePrefetchPromise;
             }
-            this.status = this.themePrefetchError instanceof projectUnavailable_1.ProjectUnavailableError
-                ? 'unavailable'
-                : 'ready';
+            if (this.themePrefetchError instanceof featureNotAvailable_1.FeatureNotAvailableError) {
+                (0, featureNotAvailable_1.warnFeatureNotAvailable)(this.themePrefetchError.feature);
+            }
+            this.status =
+                this.themePrefetchError instanceof projectUnavailable_1.ProjectUnavailableError ||
+                    (0, featureNotAvailable_1.isMobileSdkDenied)(this.themePrefetchError)
+                    ? 'unavailable'
+                    : 'ready';
             if (config.onStatusChange) {
                 config.onStatusChange(this.status);
             }
@@ -249,6 +271,17 @@ class QafkaSDK {
             return response;
         }
         catch (error) {
+            // Any plan-gated feature warns the integrator once in __DEV__, but
+            // only mobile_sdk flips the SDK to the neutral "unavailable" state a
+            // suspended project uses — a different gated feature still rejects
+            // this call with a typed FeatureNotAvailableError, but must not take
+            // down the rest of the SDK.
+            if (error instanceof featureNotAvailable_1.FeatureNotAvailableError) {
+                (0, featureNotAvailable_1.warnFeatureNotAvailable)(error.feature);
+                if ((0, featureNotAvailable_1.isMobileSdkDenied)(error)) {
+                    this.markUnavailable();
+                }
+            }
             throw error;
         }
     }
@@ -301,6 +334,14 @@ class QafkaSDK {
                 }
                 onComplete?.(response);
             }, (_error) => {
+                // Matches the sendMessage branch above; the streaming transport
+                // reports this via callback, not a rejection.
+                if (_error instanceof featureNotAvailable_1.FeatureNotAvailableError) {
+                    (0, featureNotAvailable_1.warnFeatureNotAvailable)(_error.feature);
+                    if ((0, featureNotAvailable_1.isMobileSdkDenied)(_error)) {
+                        this.markUnavailable();
+                    }
+                }
                 onError?.(_error);
             }, context, contextDescription, onToolSuggestions, // Pass tool suggestions callback
             isInitialMessage, onActionResult, // Pass action result callback
@@ -312,6 +353,12 @@ class QafkaSDK {
             onFinalChunk);
         }
         catch (error) {
+            if (error instanceof featureNotAvailable_1.FeatureNotAvailableError) {
+                (0, featureNotAvailable_1.warnFeatureNotAvailable)(error.feature);
+                if ((0, featureNotAvailable_1.isMobileSdkDenied)(error)) {
+                    this.markUnavailable();
+                }
+            }
             if (onError) {
                 onError(error instanceof Error ? error : new Error('Unknown error'));
             }

package/dist/components/Qafka.js

@@ -87,7 +87,7 @@ const { width: SCREEN_WIDTH } = react_native_1.Dimensions.get('window');
  * />
  * ```
  */
-exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlProp, devConfig, subProjectId, projectId, locale, mode = 'fullscreen', theme: themeName = 'light', customTheme, themeOverride, isAuthenticated, endUserId, endUserData, enableStreaming = true, voiceEnabled: voiceEnabledProp = true, context: userContext, contextDescription, components: customComponents, showTimestamps = true, placeholder = 'Type a message...', maxMessageLength = 500, greetingMessage, onReady, onMessageSent, onResponseReceived, onError, onUnavailable, onNavigationSuggest, onNavigationAction, onExternalSuggestion, onCardDeepLink, onCardSuggestMessage, onCardExternalNavigation, onCardShare, onCardCopy, onCardToolTrigger, onCardCTAClick, onToolSuggested, onToolDataRequested, onActionResult, onStepCompleted, onFileUploadRequest, onExtractionResult, onClose, onBack, CloseComponent, BackComponent, navigationLabelFormat, NavigationButtonComponent, voiceComponents, voiceTranscript = 'centered', toolRenderMode, }, ref) {
+exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlProp, devConfig, subProjectId, projectId, locale, mode = 'fullscreen', theme: themeName = 'light', customTheme, themeOverride, isAuthenticated, endUserId, endUserData, enableStreaming = true, voiceEnabled: voiceEnabledProp = true, context: userContext, contextDescription, components: customComponents, showTimestamps = true, placeholder = 'Type a message...', maxMessageLength = 500, greetingMessage, onReady, onMessageSent, onResponseReceived, onError, onUnavailable, onNavigationSuggest, onNavigationAction, onExternalSuggestion, onCardDeepLink, onCardSuggestMessage, onCardExternalNavigation, onCardShare, onCardCopy, onCardToolTrigger, onCardCTAClick, onToolSuggested, onToolDataRequested, onActionResult, onStepCompleted, onFileUploadRequest, onExtractionResult, onClose, onVoiceClose, onBack, CloseComponent, BackComponent, navigationLabelFormat, NavigationButtonComponent, voiceComponents, voiceTranscript = 'centered', toolRenderMode, }, ref) {
     // === ALL HOOKS FIRST (Rules of Hooks compliance) ===
     const insets = (0, react_native_safe_area_context_1.useSafeAreaInsets)();
     const { sdkReady, unavailable, error: sdkError, resolvedApiKey, resolvedApiUrl } = (0, useSDK_1.useSDK)({
@@ -149,7 +149,7 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
         endUserData: validatedEndUserData,
         onNavigationSuggest,
     });
-    const { toolStatus: voiceToolStatus, renderedTools: voiceRenderedTools, transcriptOverrideForTurn, setToolStatusManually, clearRenderedTools, connect: voiceConnect, disconnect: voiceDisconnect, pauseMic: voicePauseMic, resumeMic: voiceResumeMic, isMuted: voiceIsMuted, mute: voiceMute, unmute: voiceUnmute, toggleMute: voiceToggleMute, navigationSuggestion: voiceNavigationSuggestion, acceptNavigationSuggestion: voiceAcceptNavigation, dismissNavigationSuggestion: voiceDismissNavigation, voiceCloseReason, voiceCloseMessage, } = voiceChat;
+    const { toolStatus: voiceToolStatus, renderedTools: voiceRenderedTools, transcriptOverrideForTurn, setToolStatusManually, clearRenderedTools, connect: voiceConnect, disconnect: voiceDisconnect, pauseMic: voicePauseMic, resumeMic: voiceResumeMic, isMuted: voiceIsMuted, mute: voiceMute, unmute: voiceUnmute, toggleMute: voiceToggleMute, navigationSuggestion: voiceNavigationSuggestion, acceptNavigationSuggestion: voiceAcceptNavigation, dismissNavigationSuggestion: voiceDismissNavigation, voiceCloseReason, voiceCloseMessage, canResume: voiceCanResume, resume: voiceResume, resumeLabel: voiceResumeLabel, } = voiceChat;
     const { messages, isTyping, isSending, streamingMessage, toolStatus, flatListRef, handleSend, setMessages, setIsTyping, setStreamingMessage, } = (0, useChatMessages_1.useChatMessages)({
         enableStreaming,
         context: currentContext,
@@ -514,7 +514,14 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
 
  {/* Page 1: Voice — VoicePage paints Background edge-to-edge and
         handles its own internal safe-area padding for orb/transcript. */}
- <VoicePage_1.VoicePage state={voiceChat.state} transcript={voiceChat.transcript} userTranscript={voiceChat.userTranscript} transcriptHistory={voiceChat.transcriptHistory} transcriptMode={voiceTranscript} amplitude={voiceChat.amplitude} theme={theme} voiceComponents={voiceComponents} toolStatus={voiceToolStatus} renderedTools={voiceRenderedTools} registeredComponents={customComponents} transcriptOverrideForTurn={transcriptOverrideForTurn} DataChipListComponent={voiceComponents?.dataChipList} isMuted={voiceIsMuted} onToggleMute={voiceToggleMute} navigationSuggestion={voiceNavigationSuggestion} onNavigationAccept={voiceAcceptNavigation} onNavigationDismiss={voiceDismissNavigation} NavigationButtonComponent={NavigationButtonComponent}/>
+ <VoicePage_1.VoicePage state={voiceChat.state} transcript={voiceChat.transcript} userTranscript={voiceChat.userTranscript} transcriptHistory={voiceChat.transcriptHistory} transcriptMode={voiceTranscript} amplitude={voiceChat.amplitude} theme={theme} voiceComponents={voiceComponents} toolStatus={voiceToolStatus} renderedTools={voiceRenderedTools} registeredComponents={customComponents} transcriptOverrideForTurn={transcriptOverrideForTurn} DataChipListComponent={voiceComponents?.dataChipList} isMuted={voiceIsMuted} onToggleMute={voiceToggleMute} canResume={voiceCanResume} onResume={voiceResume} resumeLabel={voiceResumeLabel} navigationSuggestion={voiceNavigationSuggestion} onNavigationAccept={voiceAcceptNavigation} onNavigationDismiss={voiceDismissNavigation} NavigationButtonComponent={NavigationButtonComponent} 
+    // The voice page's close button only leaves voice: end the session
+    // and slide back to the chat page, which stays open.
+    onClose={() => {
+            void voiceDisconnect();
+            scrollViewRef.current?.scrollTo({ x: 0, animated: true });
+            onVoiceClose?.();
+        }}/>
  </react_native_1.ScrollView>
  </react_native_1.View>) : (<ChatPage_1.ChatPage {...chatPageProps}/>);
     return (<react_native_1.View style={[

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

@@ -64,6 +64,14 @@ export interface VoiceMuteButtonProps {
     theme: Theme;
     state: VoiceChatState;
 }
+/**
+ * Props passed to custom voice close button component
+ */
+export interface VoiceCloseButtonProps {
+    onClose: () => void;
+    theme: Theme;
+    state: VoiceChatState;
+}
 /**
  * Props passed to custom voice background component
  */
@@ -125,6 +133,11 @@ export interface VoiceComponents {
      * row in every voice layout. Defaults to a circular icon button.
      */
     VoiceMuteButton?: React.ComponentType<VoiceMuteButtonProps>;
+    /**
+     * Slot for the button that leaves the voice page and returns to the chat
+     * page, rendered in the top left corner. Defaults to a circular icon button.
+     */
+    VoiceCloseButton?: React.ComponentType<VoiceCloseButtonProps>;
     /**
      * Slot for the multi-chip list rendered when the AI calls the built-in
      * `qafka_display` tool with mode="chip".
@@ -689,6 +702,12 @@ export interface QafkaProps {
     */
     onClose?: () => void;
     /**
+    * Optional. Called when the close button on the voice page is pressed. That
+    * button only leaves voice: the voice session is ended and the widget
+    * returns to the chat page, which stays open — `onClose` is not called.
+    */
+    onVoiceClose?: () => void;
+    /**
     * Callback when back button is pressed
     * If provided, a back button will be shown in the top left corner
     */

package/dist/components/QafkaProvider.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { QafkaProps } from './Qafka.types';
-type QafkaProviderProps = Pick<QafkaProps, 'style' | 'projectId' | 'apiUrl' | 'theme' | 'themeOverride' | 'customTheme' | 'enableStreaming' | 'isAuthenticated' | 'endUserId' | 'endUserData' | 'context' | 'contextDescription' | 'components' | 'showTimestamps' | 'placeholder' | 'maxMessageLength' | 'greetingMessage' | 'title' | 'showHeader' | 'onReady' | 'onMessageSent' | 'onResponseReceived' | 'onError' | 'onNavigationSuggest' | 'onNavigationAction' | 'onToolSuggested' | 'onActionResult' | 'onStepCompleted' | 'onClose' | 'onBack' | 'CloseComponent' | 'BackComponent' | 'navigationLabelFormat' | 'NavigationButtonComponent'> & {
+type QafkaProviderProps = Pick<QafkaProps, 'style' | 'projectId' | 'apiUrl' | 'theme' | 'themeOverride' | 'customTheme' | 'enableStreaming' | 'isAuthenticated' | 'endUserId' | 'endUserData' | 'context' | 'contextDescription' | 'components' | 'showTimestamps' | 'placeholder' | 'maxMessageLength' | 'greetingMessage' | 'title' | 'showHeader' | 'onReady' | 'onMessageSent' | 'onResponseReceived' | 'onError' | 'onNavigationSuggest' | 'onNavigationAction' | 'onToolSuggested' | 'onActionResult' | 'onStepCompleted' | 'onClose' | 'onVoiceClose' | 'onBack' | 'CloseComponent' | 'BackComponent' | 'navigationLabelFormat' | 'NavigationButtonComponent'> & {
     mode?: 'floating' | 'fullscreen' | 'inline';
     position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
 };

package/dist/components/VoicePage.d.ts

@@ -44,10 +44,14 @@ interface VoicePageProps {
     }>;
     isMuted?: boolean;
     onToggleMute?: () => void;
+    canResume?: boolean;
+    onResume?: () => void;
+    resumeLabel?: string;
     navigationSuggestion?: NavigationSuggestion | null;
     onNavigationAccept?: () => void;
     onNavigationDismiss?: () => void;
     NavigationButtonComponent?: ComponentType<NavigationButtonProps>;
+    onClose?: () => void;
 }
-export declare function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode, amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn, DataChipListComponent, isMuted, onToggleMute, navigationSuggestion, onNavigationAccept, onNavigationDismiss, NavigationButtonComponent, }: VoicePageProps): React.JSX.Element;
+export declare function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode, amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn, DataChipListComponent, isMuted, onToggleMute, canResume, onResume, resumeLabel, navigationSuggestion, onNavigationAccept, onNavigationDismiss, NavigationButtonComponent, onClose, }: VoicePageProps): React.JSX.Element;
 export {};

package/dist/components/VoicePage.js

@@ -306,6 +306,19 @@ function DefaultVoiceMuteButton({ isMuted, onToggle, theme, }) {
  {isMuted ? <react_native_1.View style={[muteStyles.slash, { backgroundColor: fg }]}/> : null}
  </react_native_1.Pressable>);
 }
+function DefaultVoiceCloseButton({ onClose, theme }) {
+    return (<react_native_1.Pressable onPress={onClose} hitSlop={8} accessibilityRole="button" accessibilityLabel="End voice chat" style={({ pressed }) => [
+            muteStyles.button,
+            {
+                backgroundColor: theme?.colors?.surface ?? 'rgba(0,0,0,0.06)',
+                opacity: pressed ? 0.75 : 1,
+            },
+        ]}>
+ <react_native_1.Text style={{ fontSize: 24, lineHeight: 26, color: theme?.colors?.text ?? '#111' }}>
+ {'×'}
+ </react_native_1.Text>
+ </react_native_1.Pressable>);
+}
 /**
  * Minimal microphone glyph built with stock Views — capsule body, stand
  * post, and base bar. No external icon font, no SVG, no Skia.
@@ -408,7 +421,7 @@ function ChatTranscript({ history, liveAiText, state, primaryTextColor, secondar
  </react_native_1.View>);
 }
 // --- Main component ---
-function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode = 'centered', amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn = false, DataChipListComponent, isMuted = false, onToggleMute, navigationSuggestion, onNavigationAccept, onNavigationDismiss, NavigationButtonComponent, }) {
+function VoicePage({ state, transcript, userTranscript, transcriptHistory, transcriptMode = 'centered', amplitude, theme, voiceComponents, toolStatus, renderedTools, registeredComponents, transcriptOverrideForTurn = false, DataChipListComponent, isMuted = false, onToggleMute, canResume = false, onResume, resumeLabel, navigationSuggestion, onNavigationAccept, onNavigationDismiss, NavigationButtonComponent, onClose, }) {
     const Indicator = voiceComponents?.VoiceIndicator || DefaultVoiceIndicator;
     const Background = voiceComponents?.VoiceBackground || DefaultVoiceBackground;
     const Transcript = voiceComponents?.VoiceTranscript || DefaultVoiceTranscript;
@@ -416,6 +429,19 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
     // Disable rendering the button entirely when there's nothing to drive it,
     // e.g. consumer drives the SDK without using useVoiceChat's mute layer.
     const showMute = typeof onToggleMute === 'function';
+    // The session ended while this page stayed on screen (see
+    // decide-voice-resume.ts): the mic button and the indicator re-open it
+    // instead of toggling mute.
+    const resumable = canResume && typeof onResume === 'function';
+    const onMicPress = resumable ? onResume : onToggleMute;
+    const resumeHint = resumable && resumeLabel ? (<react_native_1.Text style={{ marginTop: 12, fontSize: 14, color: STATE_COLORS.idle }}>
+ {resumeLabel}
+ </react_native_1.Text>) : null;
+    // Leaves voice and returns to the chat page, so that does not require
+    // swiping back. Top left: the mic button owns the top right corner.
+    const CloseButton = voiceComponents?.VoiceCloseButton || DefaultVoiceCloseButton;
+    const showClose = typeof onClose === 'function';
+    const closeButton = showClose ? (<CloseButton onClose={onClose} theme={theme} state={state}/>) : null;
     const hasToolUI = !transcriptOverrideForTurn && (renderedTools?.length ?? 0) > 0;
     // When tool UI is rendered, the compact status bar takes over regardless of
     // chosen mode — preserves the single-screen / hands-free experience.
@@ -455,6 +481,7 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
                 borderBottomColor: 'rgba(0,0,0,0.08)',
                 backgroundColor: theme?.colors?.background ?? '#fff',
             }}>
+ {closeButton}
  <react_native_1.View style={{
                 width: 44,
                 height: 44,
@@ -476,19 +503,19 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
  </react_native_1.View>
  </react_native_1.View>
 
- <react_native_1.View style={{ flex: 1 }}>
+ <react_native_1.Pressable style={{ flex: 1 }} disabled={!resumable} onPress={onResume}>
  <react_native_1.Text style={{
                 fontSize: 13,
                 fontWeight: react_native_1.Platform.select({ ios: '600', default: 'bold' }),
                 color: STATE_COLORS[state],
             }} numberOfLines={1}>
- {STATE_LABELS[state]}
+ {resumable && resumeLabel ? resumeLabel : STATE_LABELS[state]}
  </react_native_1.Text>
  {toolStatus?.loadingMessage ? (<react_native_1.Text style={{ fontSize: 11, color: '#888', marginTop: 1 }} numberOfLines={1}>
  {toolStatus.loadingMessage}
  </react_native_1.Text>) : null}
- </react_native_1.View>
- {showMute ? (<MuteButton isMuted={isMuted} onToggle={onToggleMute} theme={theme} state={state}/>) : null}
+ </react_native_1.Pressable>
+ {showMute ? (<MuteButton isMuted={isMuted} onToggle={onMicPress} theme={theme} state={state}/>) : null}
  </react_native_1.View>) : isChatLayout ? (
         // Chat layout: orb anchored at the top, chat history fills the rest.
         // The orb moves up (vs. centered) to give the transcript room to breathe.
@@ -498,9 +525,10 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
                 width: '100%',
                 paddingTop: 32,
             }}>
- <react_native_1.View style={{ alignItems: 'center', justifyContent: 'center' }}>
+ <react_native_1.Pressable disabled={!resumable} onPress={onResume} accessibilityRole={resumable ? 'button' : undefined} accessibilityLabel={resumable ? resumeLabel : undefined} style={{ alignItems: 'center', justifyContent: 'center' }}>
  <Indicator state={state} amplitude={amplitude} theme={theme} isMuted={isMuted}/>
- </react_native_1.View>
+ </react_native_1.Pressable>
+ {resumeHint}
 
  {toolStatus ? (<react_native_1.View style={{ marginTop: 4, alignItems: 'center' }}>
  <ToolStatusPill_1.ToolStatusPill message={toolStatus.loadingMessage} theme={theme}/>
@@ -517,9 +545,10 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
                 alignItems: 'center',
                 justifyContent: 'center',
             }}>
- <react_native_1.View style={{ alignItems: 'center', justifyContent: 'center' }}>
+ <react_native_1.Pressable disabled={!resumable} onPress={onResume} accessibilityRole={resumable ? 'button' : undefined} accessibilityLabel={resumable ? resumeLabel : undefined} style={{ alignItems: 'center', justifyContent: 'center' }}>
  <Indicator state={state} amplitude={amplitude} theme={theme} isMuted={isMuted}/>
- </react_native_1.View>
+ </react_native_1.Pressable>
+ {resumeHint}
 
  {toolStatus ? (<react_native_1.View style={{ marginTop: 12, alignItems: 'center' }}>
  <ToolStatusPill_1.ToolStatusPill message={toolStatus.loadingMessage} theme={theme}/>
@@ -595,6 +624,14 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
  </react_native_1.ScrollView>) : null}
  </react_native_1.View>
 
+ {showClose && !hasToolUI ? (<react_native_1.View style={{
+                position: 'absolute',
+                top: insets.top + 12,
+                left: 16,
+            }}>
+ {closeButton}
+ </react_native_1.View>) : null}
+
  {showMute && !hasToolUI ? (<react_native_1.View style={{
                 position: 'absolute',
                 // Absolute children aren't pushed by the parent's safe-area paddingTop,
@@ -602,7 +639,7 @@ function VoicePage({ state, transcript, userTranscript, transcriptHistory, trans
                 top: insets.top + 12,
                 right: 16,
             }}>
- <MuteButton isMuted={isMuted} onToggle={onToggleMute} theme={theme} state={state}/>
+ <MuteButton isMuted={isMuted} onToggle={onMicPress} theme={theme} state={state}/>
  </react_native_1.View>) : null}
  </react_native_1.View>
  </Background>);

package/dist/components/index.d.ts

@@ -3,7 +3,7 @@
  */
 export { QafkaProvider } from './QafkaProvider';
 export { Qafka } from './Qafka';
-export type { VoiceComponents, VoiceIndicatorProps, VoiceBackgroundProps, VoiceTranscriptProps, VoiceMuteButtonProps, QafkaHandle } from './Qafka.types';
+export type { VoiceComponents, VoiceIndicatorProps, VoiceBackgroundProps, VoiceTranscriptProps, VoiceMuteButtonProps, VoiceCloseButtonProps, QafkaHandle } from './Qafka.types';
 export type { ToolResponseMode } from './Qafka.types';
 export type { QafkaProps, QafkaProjectIds, ProjectIdOf } from './Qafka.types';
 export { MessageBubble } from './MessageBubble';

package/dist/decide-voice-close.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.classifyVoiceClose = classifyVoiceClose;
+const featureNotAvailable_1 = require("./services/featureNotAvailable");
 function classifyVoiceClose(event) {
     const code = event?.code;
     const reason = event?.reason;
@@ -10,7 +11,15 @@ function classifyVoiceClose(event) {
     if (code === 4003 || reason === 'VOICE_NOT_ALLOWED') {
         return 'not_allowed';
     }
-    if (code === 4010 || reason === 'project_unavailable') {
+    // 4010 = project suspended; close code 4012 is shared by every
+    // feature-gated close (see featureNotAvailable.ts), so only the
+    // mobile_sdk-specific reason string maps here — mobile_sdk gates the
+    // whole SDK, so it gets the same neutral "assistant unavailable" UX as a
+    // suspended project. A close for a different gated feature (were voice
+    // ever gated on one) falls through to 'other' instead.
+    if (code === 4010 ||
+        reason === 'project_unavailable' ||
+        reason === featureNotAvailable_1.MOBILE_SDK_FEATURE_NOT_AVAILABLE_REASON) {
         return 'project_unavailable';
     }
     return 'other';

package/dist/decide-voice-resume.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Decides whether the voice page should offer to re-open the session.
+ *
+ * A session can end while the voice page stays on screen — the assistant
+ * navigated to a host screen and the user came back, the app went to the
+ * background, or the connection dropped. A session is otherwise only opened
+ * when the pager lands on the voice page, so without this offer the page
+ * would sit idle with no way back in short of swiping away and back.
+ *
+ * Not offered before the first session (the swipe opens it on its own), nor
+ * when the server ended the session because voice is unavailable — that case
+ * falls back to text chat instead. Kept as a pure function so it is
+ * unit-testable without loading the native-bound voice hook.
+ */
+export declare function canResumeVoice(input: {
+    state: string;
+    sessionEnded: boolean;
+    closeReason: string | null | undefined;
+}): boolean;
+/** Locale-aware label for the resume affordance. */
+export declare function voiceResumeLabel(locale?: string): string;

package/dist/decide-voice-resume.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canResumeVoice = canResumeVoice;
+exports.voiceResumeLabel = voiceResumeLabel;
+/**
+ * Decides whether the voice page should offer to re-open the session.
+ *
+ * A session can end while the voice page stays on screen — the assistant
+ * navigated to a host screen and the user came back, the app went to the
+ * background, or the connection dropped. A session is otherwise only opened
+ * when the pager lands on the voice page, so without this offer the page
+ * would sit idle with no way back in short of swiping away and back.
+ *
+ * Not offered before the first session (the swipe opens it on its own), nor
+ * when the server ended the session because voice is unavailable — that case
+ * falls back to text chat instead. Kept as a pure function so it is
+ * unit-testable without loading the native-bound voice hook.
+ */
+function canResumeVoice(input) {
+    return input.state === 'idle' && input.sessionEnded && !input.closeReason;
+}
+/** Locale-aware label for the resume affordance. */
+function voiceResumeLabel(locale) {
+    return locale?.toLowerCase().startsWith('tr')
+        ? 'Devam etmek için dokunun'
+        : 'Tap to continue';
+}

package/dist/hooks/useChatMessages.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.useChatMessages = void 0;
 const react_1 = require("react");
 const QafkaSDK_1 = require("../QafkaSDK");
+const featureNotAvailable_1 = require("../services/featureNotAvailable");
 const Qafka_utils_1 = require("../components/Qafka.utils");
 const joinNarration_1 = require("../utils/joinNarration");
 const extractionContinuation_1 = require("../utils/extractionContinuation");
@@ -534,11 +535,17 @@ const useChatMessages = ({ enableStreaming = true, context = {}, contextDescript
         setIsSending(false);
         setToolStatus(null);
         finalChunkBufferRef.current = '';
-        // Project suspended mid-session: flip the SDK to 'unavailable' instead of
-        // treating this as a normal error. QafkaSDK.markUnavailable() notifies the
-        // same onStatusChange listener useSDK subscribes to, so `onUnavailable`
-        // fires there — no onError call and no error bubble here.
-        if (err?.code === 'PROJECT_UNAVAILABLE') {
+        // Project suspended, or the plan does not include mobile_sdk, mid-session:
+        // flip the SDK to 'unavailable' instead of treating this as a normal
+        // error. QafkaSDK.markUnavailable() notifies the same onStatusChange
+        // listener useSDK subscribes to, so `onUnavailable` fires there — no
+        // onError call and no error bubble here. The __DEV__ upgrade warning is
+        // already emitted by QafkaSDK before this hook sees the error, so it
+        // isn't repeated here. A FEATURE_NOT_AVAILABLE for a feature other than
+        // mobile_sdk (e.g. card_templates) is NOT this case — it falls through
+        // to the normal onError/error-bubble handling below, since it doesn't
+        // gate the whole SDK.
+        if (err?.code === 'PROJECT_UNAVAILABLE' || (0, featureNotAvailable_1.isMobileSdkDenied)(err)) {
             QafkaSDK_1.QafkaSDK.getInstance().markUnavailable();
             return;
         }

package/dist/hooks/useVoiceChat.d.ts

@@ -133,5 +133,14 @@ interface UseVoiceChatResult {
     voiceCloseReason: 'minutes_exhausted' | null;
     /** Locale-aware copy to show alongside `voiceCloseReason`, or `null`. */
     voiceCloseMessage: string | null;
+    /**
+     * True when the session has ended while the voice page may still be on
+     * screen, so the page should offer `resume` instead of sitting idle.
+     */
+    canResume: boolean;
+    /** Re-opens the voice session after it ended. */
+    resume: () => Promise<void>;
+    /** Locale-aware label for the resume affordance. */
+    resumeLabel: string;
 }
 export declare function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale, onToolSuggested, toolRenderMode, getSessionToken, endUserId, endUserData, onNavigationSuggest, }: UseVoiceChatOptions): UseVoiceChatResult;

package/dist/hooks/useVoiceChat.js

@@ -7,6 +7,7 @@ const RealtimeService_1 = require("../services/RealtimeService");
 const QafkaAudio_1 = require("../native/QafkaAudio");
 const decide_voice_navigation_1 = require("../decide-voice-navigation");
 const decide_voice_close_1 = require("../decide-voice-close");
+const decide_voice_resume_1 = require("../decide-voice-resume");
 /**
  * Neutral, locale-aware copy shown when the server ends a voice session
  * because it can no longer be continued. Mirrors `unavailableMessage()` in
@@ -21,6 +22,9 @@ function voiceUnavailableMessage(locale) {
 function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale, onToolSuggested, toolRenderMode = 'upsert', getSessionToken, endUserId, endUserData, onNavigationSuggest, }) {
     const [state, setState] = (0, react_1.useState)('idle');
     const [voiceCloseReason, setVoiceCloseReason] = (0, react_1.useState)(null);
+    // True once a session has ended while this hook stays mounted. Drives the
+    // voice page's resume affordance (see decide-voice-resume.ts).
+    const [sessionEnded, setSessionEnded] = (0, react_1.useState)(false);
     const [voiceCloseMessage, setVoiceCloseMessage] = (0, react_1.useState)(null);
     const localeRef = (0, react_1.useRef)(locale);
     (0, react_1.useEffect)(() => {
@@ -180,12 +184,14 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale,
                 setVoiceCloseReason(null);
                 setVoiceCloseMessage(null);
                 setState('idle');
+                setSessionEnded(true);
                 setNavigationSuggestion(null);
                 pendingNavDisconnectRef.current = false;
                 return;
             }
             case 'error':
                 setState('idle');
+                setSessionEnded(true);
                 return;
             case 'tool_status':
                 setToolStatus({
@@ -424,6 +430,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale,
             return;
         }
         setState('connecting');
+        setSessionEnded(false);
         setVoiceCloseReason(null);
         setVoiceCloseMessage(null);
         const service = new RealtimeService_1.RealtimeService(apiUrl, apiKey);
@@ -459,6 +466,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale,
         }
         catch {
             setState('idle');
+            setSessionEnded(true);
             serviceRef.current = null;
         }
     }, [apiUrl, apiKey, handleEvent, userContext, contextDescription, getSessionToken, endUserId, endUserData]);
@@ -468,6 +476,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale,
         await serviceRef.current?.disconnect();
         serviceRef.current = null;
         setState('idle');
+        setSessionEnded(true);
         setTranscript('');
         setUserTranscript('');
         setTranscriptHistory([]);
@@ -483,6 +492,15 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale,
     (0, react_1.useEffect)(() => {
         disconnectRef.current = disconnect;
     }, [disconnect]);
+    // Re-opens the session from the voice page. A session that ended without
+    // going through disconnect() (connection error, unexpected close) leaves its
+    // service behind, which connect() would treat as still live — clear it first.
+    const resume = (0, react_1.useCallback)(async () => {
+        if (serviceRef.current && !serviceRef.current.isConnected) {
+            await disconnect();
+        }
+        await connect();
+    }, [connect, disconnect]);
     const pauseMic = (0, react_1.useCallback)(async () => {
         await serviceRef.current?.pauseMic();
     }, []);
@@ -559,5 +577,8 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale,
         dismissNavigationSuggestion,
         voiceCloseReason,
         voiceCloseMessage,
+        canResume: (0, decide_voice_resume_1.canResumeVoice)({ state, sessionEnded, closeReason: voiceCloseReason }),
+        resume,
+        resumeLabel: (0, decide_voice_resume_1.voiceResumeLabel)(locale),
     };
 }

package/dist/index.d.ts

@@ -3,6 +3,7 @@
  * AI-powered conversational interface with navigation intelligence
  */
 export { QafkaSDK, getSDK } from './QafkaSDK';
+export { FeatureNotAvailableError } from './services/featureNotAvailable';
 export declare const getVersion: () => string;
 export declare const isVersionAtLeast: (minVersion: string) => boolean;
 export * from './components';

package/dist/index.js

@@ -18,11 +18,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isVersionAtLeast = exports.getVersion = exports.getSDK = exports.QafkaSDK = void 0;
+exports.isVersionAtLeast = exports.getVersion = exports.FeatureNotAvailableError = exports.getSDK = exports.QafkaSDK = void 0;
 // Main SDK export
 var QafkaSDK_1 = require("./QafkaSDK");
 Object.defineProperty(exports, "QafkaSDK", { enumerable: true, get: function () { return QafkaSDK_1.QafkaSDK; } });
 Object.defineProperty(exports, "getSDK", { enumerable: true, get: function () { return QafkaSDK_1.getSDK; } });
+var featureNotAvailable_1 = require("./services/featureNotAvailable");
+Object.defineProperty(exports, "FeatureNotAvailableError", { enumerable: true, get: function () { return featureNotAvailable_1.FeatureNotAvailableError; } });
 const package_json_1 = require("../package.json");
 const getVersion = () => package_json_1.version;
 exports.getVersion = getVersion;

package/dist/services/AttestationManager.js

@@ -38,6 +38,7 @@ const react_native_1 = require("react-native");
 const storage_1 = require("./storage");
 const NativeAttestation = __importStar(require("../native/QafkaAttestation"));
 const QafkaAttestation_1 = require("../native/QafkaAttestation");
+const featureNotAvailable_1 = require("./featureNotAvailable");
 class AttestationManager {
     config;
     sessionToken = null;
@@ -273,6 +274,11 @@ class AttestationManager {
         }
         this.log(`[Qafka:init] challenge status=${response.status}`);
         if (!response.ok) {
+            const errorData = await response.json().catch(() => ({}));
+            const unavailableFeature = (0, featureNotAvailable_1.getUnavailableFeature)(response.status, errorData);
+            if (unavailableFeature) {
+                throw new featureNotAvailable_1.FeatureNotAvailableError(unavailableFeature, errorData.message);
+            }
             throw new Error(`Challenge request failed: ${response.status}`);
         }
         const data = await response.json();
@@ -300,6 +306,10 @@ class AttestationManager {
         this.log(`[Qafka:init] attest status=${response.status}`);
         if (!response.ok) {
             const errorData = await response.json().catch(() => ({}));
+            const unavailableFeature = (0, featureNotAvailable_1.getUnavailableFeature)(response.status, errorData);
+            if (unavailableFeature) {
+                throw new featureNotAvailable_1.FeatureNotAvailableError(unavailableFeature, errorData.message);
+            }
             throw new Error(`Attestation failed: ${response.status} — ${errorData.message || errorData.error || 'Unknown error'}`);
         }
         return response.json();

package/dist/services/BackendService.js

@@ -5,6 +5,7 @@ const react_native_1 = require("react-native");
 const package_json_1 = require("../../package.json");
 const QafkaAttestation_1 = require("../native/QafkaAttestation");
 const projectUnavailable_1 = require("./projectUnavailable");
+const featureNotAvailable_1 = require("./featureNotAvailable");
 /**
  * Backend API Service using native fetch
  */
@@ -282,6 +283,13 @@ class BackendService {
             if ((0, projectUnavailable_1.isProjectUnavailable)(response.status, errorData)) {
                 throw new projectUnavailable_1.ProjectUnavailableError(errorMessage);
             }
+            // Plan does not include this SDK channel (e.g. `mobile_sdk`) — a
+            // distinct signal from the other 403 branches below, callers branch on
+            // `FeatureNotAvailableError` / `code === 'FEATURE_NOT_AVAILABLE'`.
+            const unavailableFeature = (0, featureNotAvailable_1.getUnavailableFeature)(response.status, errorData);
+            if (unavailableFeature) {
+                throw new featureNotAvailable_1.FeatureNotAvailableError(unavailableFeature, errorMessage);
+            }
             // 401: Unauthorized (Invalid/Missing API Key)
             if (response.status === 401) {
                 if (errorCode === 'MISSING_API_KEY') {
@@ -432,9 +440,10 @@ class BackendService {
             return this.handleResponse(response);
         }
         catch (error) {
-            // Preserve ProjectUnavailableError as-is — callers (QafkaSDK.initialize)
-            // branch on `instanceof`, so re-wrapping here would lose that signal.
-            if (error instanceof projectUnavailable_1.ProjectUnavailableError) {
+            // Preserve ProjectUnavailableError / FeatureNotAvailableError as-is —
+            // callers (QafkaSDK.initialize) branch on `instanceof`, so re-wrapping
+            // here would lose that signal.
+            if (error instanceof projectUnavailable_1.ProjectUnavailableError || error instanceof featureNotAvailable_1.FeatureNotAvailableError) {
                 throw error;
             }
             throw new Error(error.message || 'Failed to fetch theme');
@@ -686,6 +695,13 @@ class BackendService {
                         onError(unavailableErr);
                         return;
                     }
+                    const unavailableFeature = (0, featureNotAvailable_1.getUnavailableFeature)(xhr.status, parsedBody);
+                    if (unavailableFeature) {
+                        const featureErr = new featureNotAvailable_1.FeatureNotAvailableError(unavailableFeature, serverMessage);
+                        featureErr.status = xhr.status;
+                        onError(featureErr);
+                        return;
+                    }
                     // In dev, a 401 with a test key almost always means the rotated dev
                     // key is stale. Surface an actionable hint instead of a bare HTTP error.
                     if (__DEV__ && xhr.status === 401 && this.apiKey?.startsWith('qafka_test_')) {

package/dist/services/featureNotAvailable.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared helpers for the "feature not available" state: when the project's
+ * plan does not include a given SDK feature (e.g. `mobile_sdk`), the backend
+ * answers HTTP 403 `{ error: 'feature_not_available', feature: '<f>',
+ * message }` on every request for that channel, and closes a voice
+ * WebSocket with code 4012. The SDK maps this to the same neutral
+ * "assistant unavailable" UX as a suspended project (see
+ * `./projectUnavailable.ts`) — no error bubble — and, in `__DEV__` only
+ * (repo rule: no bare `console.*`), warns the developer once per feature
+ * with an actionable upgrade message.
+ */
+/** WebSocket close code the realtime/voice backend uses for this signal. */
+export declare const FEATURE_NOT_AVAILABLE_CLOSE_CODE = 4012;
+/**
+ * True when a response is the specific "feature not available" signal, as
+ * opposed to any other 403 (bundle id, platform, permission, project
+ * suspension, ...). Returns the gated feature name, or `'unknown'` when the
+ * body confirms the signal but omits the feature, or `null` when the
+ * response is not this signal at all.
+ */
+export declare function getUnavailableFeature(status: number, body: unknown): string | null;
+/**
+ * Thrown by the transport layer when a request fails because the project's
+ * plan does not include the requested feature. Callers branch on `code`,
+ * not `instanceof`, where they only have a plain error (e.g. across the
+ * streaming/XHR boundary) — mirroring `ProjectUnavailableError`.
+ */
+export declare class FeatureNotAvailableError extends Error {
+    code: string;
+    feature: string;
+    /** HTTP status of the response that produced this error, when known. */
+    status?: number;
+    constructor(feature: string, message?: string);
+}
+/**
+ * Developer-facing (not end-user-facing) message: names the gated feature
+ * and points at the upgrade path. Used both as the default
+ * `FeatureNotAvailableError` message and as the `__DEV__` console warning.
+ */
+export declare function featureNotAvailableMessage(feature: string): string;
+/**
+ * Warns the developer, once per feature per app run, that a plan-gated SDK
+ * feature was rejected. Only runs in `__DEV__` — production builds never
+ * print this (repo rule: no bare `console.*`). The end user is unaffected;
+ * they see the neutral "unavailable" UX, not this message.
+ */
+export declare function warnFeatureNotAvailable(feature: string): void;
+/** Test-only: clears the once-per-feature warning dedupe state. */
+export declare function resetFeatureWarningsForTests(): void;
+/**
+ * True when `err` is a `FeatureNotAvailableError` for the `mobile_sdk`
+ * feature specifically. Only `mobile_sdk` justifies flipping the whole SDK
+ * to the neutral 'unavailable' state (the same UX as a suspended project):
+ * it gates every request the SDK makes. Any other plan-gated feature (e.g.
+ * a card-template or tool-specific flag) still surfaces as a typed
+ * `FeatureNotAvailableError` to the caller, but must not take down the rest
+ * of the SDK — a project can be denied one feature and fine on everything
+ * else. Callers still call `warnFeatureNotAvailable(err.feature)` for every
+ * feature; only the unavailable flip is mobile_sdk-specific.
+ */
+export declare function isMobileSdkDenied(err: unknown): boolean;
+/** WS close reason string the backend sends when a voice session is closed
+ * because the project's plan does not include `mobile_sdk`. Voice-only:
+ * used by `decide-voice-close.ts` to keep the 'unavailable' outcome scoped
+ * to this specific feature rather than any `feature_not_available` close. */
+export declare const MOBILE_SDK_FEATURE_NOT_AVAILABLE_REASON = "FEATURE_NOT_AVAILABLE:mobile_sdk";

package/dist/services/featureNotAvailable.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Shared helpers for the "feature not available" state: when the project's
+ * plan does not include a given SDK feature (e.g. `mobile_sdk`), the backend
+ * answers HTTP 403 `{ error: 'feature_not_available', feature: '<f>',
+ * message }` on every request for that channel, and closes a voice
+ * WebSocket with code 4012. The SDK maps this to the same neutral
+ * "assistant unavailable" UX as a suspended project (see
+ * `./projectUnavailable.ts`) — no error bubble — and, in `__DEV__` only
+ * (repo rule: no bare `console.*`), warns the developer once per feature
+ * with an actionable upgrade message.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MOBILE_SDK_FEATURE_NOT_AVAILABLE_REASON = exports.FeatureNotAvailableError = exports.FEATURE_NOT_AVAILABLE_CLOSE_CODE = void 0;
+exports.getUnavailableFeature = getUnavailableFeature;
+exports.featureNotAvailableMessage = featureNotAvailableMessage;
+exports.warnFeatureNotAvailable = warnFeatureNotAvailable;
+exports.resetFeatureWarningsForTests = resetFeatureWarningsForTests;
+exports.isMobileSdkDenied = isMobileSdkDenied;
+/** WebSocket close code the realtime/voice backend uses for this signal. */
+exports.FEATURE_NOT_AVAILABLE_CLOSE_CODE = 4012;
+/** Human-readable names for features callers may see in the 403 body. */
+const FEATURE_DISPLAY_NAMES = {
+    mobile_sdk: 'Mobile SDK',
+    web_sdk: 'Web SDK',
+};
+/**
+ * True when a response is the specific "feature not available" signal, as
+ * opposed to any other 403 (bundle id, platform, permission, project
+ * suspension, ...). Returns the gated feature name, or `'unknown'` when the
+ * body confirms the signal but omits the feature, or `null` when the
+ * response is not this signal at all.
+ */
+function getUnavailableFeature(status, body) {
+    if (status !== 403)
+        return null;
+    if (!body || typeof body !== 'object')
+        return null;
+    if (body.error !== 'feature_not_available')
+        return null;
+    const feature = body.feature;
+    return typeof feature === 'string' && feature.length > 0 ? feature : 'unknown';
+}
+/**
+ * Thrown by the transport layer when a request fails because the project's
+ * plan does not include the requested feature. Callers branch on `code`,
+ * not `instanceof`, where they only have a plain error (e.g. across the
+ * streaming/XHR boundary) — mirroring `ProjectUnavailableError`.
+ */
+class FeatureNotAvailableError extends Error {
+    code = 'FEATURE_NOT_AVAILABLE';
+    feature;
+    /** HTTP status of the response that produced this error, when known. */
+    status;
+    constructor(feature, message) {
+        super(message ?? featureNotAvailableMessage(feature));
+        this.name = 'FeatureNotAvailableError';
+        this.feature = feature;
+        Object.setPrototypeOf(this, FeatureNotAvailableError.prototype);
+    }
+}
+exports.FeatureNotAvailableError = FeatureNotAvailableError;
+/**
+ * Developer-facing (not end-user-facing) message: names the gated feature
+ * and points at the upgrade path. Used both as the default
+ * `FeatureNotAvailableError` message and as the `__DEV__` console warning.
+ */
+function featureNotAvailableMessage(feature) {
+    const displayName = FEATURE_DISPLAY_NAMES[feature] ?? feature;
+    return `[Qafka] ${displayName} is not available on the current plan. Upgrade the project's plan in the Dashboard to enable it.`;
+}
+const warnedFeatures = new Set();
+/**
+ * Warns the developer, once per feature per app run, that a plan-gated SDK
+ * feature was rejected. Only runs in `__DEV__` — production builds never
+ * print this (repo rule: no bare `console.*`). The end user is unaffected;
+ * they see the neutral "unavailable" UX, not this message.
+ */
+function warnFeatureNotAvailable(feature) {
+    if (!__DEV__)
+        return;
+    if (warnedFeatures.has(feature))
+        return;
+    warnedFeatures.add(feature);
+    console.warn(featureNotAvailableMessage(feature));
+}
+/** Test-only: clears the once-per-feature warning dedupe state. */
+function resetFeatureWarningsForTests() {
+    warnedFeatures.clear();
+}
+/**
+ * True when `err` is a `FeatureNotAvailableError` for the `mobile_sdk`
+ * feature specifically. Only `mobile_sdk` justifies flipping the whole SDK
+ * to the neutral 'unavailable' state (the same UX as a suspended project):
+ * it gates every request the SDK makes. Any other plan-gated feature (e.g.
+ * a card-template or tool-specific flag) still surfaces as a typed
+ * `FeatureNotAvailableError` to the caller, but must not take down the rest
+ * of the SDK — a project can be denied one feature and fine on everything
+ * else. Callers still call `warnFeatureNotAvailable(err.feature)` for every
+ * feature; only the unavailable flip is mobile_sdk-specific.
+ */
+function isMobileSdkDenied(err) {
+    return err instanceof FeatureNotAvailableError && err.feature === 'mobile_sdk';
+}
+/** WS close reason string the backend sends when a voice session is closed
+ * because the project's plan does not include `mobile_sdk`. Voice-only:
+ * used by `decide-voice-close.ts` to keep the 'unavailable' outcome scoped
+ * to this specific feature rather than any `feature_not_available` close. */
+exports.MOBILE_SDK_FEATURE_NOT_AVAILABLE_REASON = 'FEATURE_NOT_AVAILABLE:mobile_sdk';

package/docs/qafka-tool-authoring-guide.md

@@ -288,9 +288,10 @@ You may optionally restyle the chips via `voiceComponents.dataChipList` / `voice
   the inverse of `context`.
 - **`subProjectId`** — multi-tenant routing.
 - **`locale`** — BCP-47 locale.
-- **`onUnavailable`** — fires when the project becomes unavailable (suspended). The chat
-  screen stays mounted and shows a neutral message in place of the normal chat surface; not
-  treated as an error (`onError` is not also called). Use it to hide your own entry point —
+- **`onUnavailable`** — fires when the project becomes unavailable (suspended, or the mobile
+  SDK is not enabled for it). The chat screen stays mounted and shows a neutral message in
+  place of the normal chat surface; not treated as an error (`onError` is not also called).
+  Use it to hide your own entry point —
   e.g. a launcher button or nav item — so users can't open a chat screen with nothing to say:
   ```tsx
   const [chatAvailable, setChatAvailable] = useState(true);
@@ -298,6 +299,10 @@ You may optionally restyle the chips via `voiceComponents.dataChipList` / `voice
   <Qafka onUnavailable={() => setChatAvailable(false)} />
   {chatAvailable && <LauncherButton onPress={openChat} />}
   ```
+- **`onVoiceClose`** — optional; fires when the close button on the voice page is pressed.
+  That button only leaves voice: the voice session ends and the widget returns to the chat
+  page, which stays open. `onClose` is not called — it still belongs to the chat page's own
+  close button. Restyle the button via `voiceComponents.VoiceCloseButton`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qafka/react-native",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "description": "Drop-in AI assistant for React Native: chat, voice, and tool execution with screen-aware navigation.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",