@qafka/react-native 2.6.0 → 2.8.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [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
+
+- Voice session ended by the server: when the backend ends a voice session because voice time is no longer available for the project, the SDK now closes voice cleanly, returns the user to the text chat and shows a neutral, localized message ("Voice chat is currently unavailable. You can keep chatting by text." / Turkish when `locale` starts with `tr`). Text chat keeps working. This applies both when voice is opened and during an ongoing call.
+
+### Changed
+
+- Voice sessions closed by the server mid-call are now distinguished from network drops and user-initiated disconnects, so an unexpected close no longer leaves the voice screen in a connecting or listening state. No public API changes.
+
 ## [2.6.0] — 2026-09-15
 
 ### 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

@@ -135,6 +135,7 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
         apiKey: resolvedApiKey || '',
         userContext: currentContext,
         contextDescription,
+        locale,
         onToolSuggested,
         toolRenderMode,
         // Forward the device-attestation session token so the realtime WS
@@ -148,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, } = 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,
@@ -398,6 +399,34 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
             voiceChat.pauseMic();
         }
     }, [voiceChat]);
+    // The server can end a voice session for a reason the user should be told
+    // about (currently only when it can no longer continue). useVoiceChat
+    // already tears the session down; here we mirror the user's own "swipe
+    // back to chat" gesture and drop its message into the transcript the same
+    // way a failed send does (see useChatMessages' fallback error bubble) —
+    // reusing the existing chat-bubble UI instead of adding a new surface.
+    const handledVoiceCloseRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (voiceCloseReason === 'minutes_exhausted') {
+            if (handledVoiceCloseRef.current)
+                return;
+            handledVoiceCloseRef.current = true;
+            scrollViewRef.current?.scrollTo({ x: 0, animated: true });
+            setMessages((prev) => [
+                ...prev,
+                {
+                    id: `voice_closed_${Date.now()}`,
+                    role: 'assistant',
+                    text: voiceCloseMessage ?? '',
+                    content: voiceCloseMessage ?? '',
+                    timestamp: new Date(),
+                },
+            ]);
+        }
+        else {
+            handledVoiceCloseRef.current = false;
+        }
+    }, [voiceCloseReason, voiceCloseMessage, setMessages]);
     // Card CTA host callbacks bundle. Stable reference via useMemo
     // so MessageBubble's CardRuntimeProvider doesn't re-mount on every render.
     // MUST be declared before the conditional returns below — Rules of Hooks.
@@ -485,7 +514,7 @@ 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}/>
  </react_native_1.ScrollView>
  </react_native_1.View>) : (<ChatPage_1.ChatPage {...chatPageProps}/>);
     return (<react_native_1.View style={[

package/dist/components/VoicePage.d.ts

@@ -44,10 +44,13 @@ interface VoicePageProps {
     }>;
     isMuted?: boolean;
     onToggleMute?: () => void;
+    canResume?: boolean;
+    onResume?: () => void;
+    resumeLabel?: string;
     navigationSuggestion?: NavigationSuggestion | null;
     onNavigationAccept?: () => void;
     onNavigationDismiss?: () => void;
     NavigationButtonComponent?: ComponentType<NavigationButtonProps>;
 }
-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, }: VoicePageProps): React.JSX.Element;
 export {};

package/dist/components/VoicePage.js

@@ -408,7 +408,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, }) {
     const Indicator = voiceComponents?.VoiceIndicator || DefaultVoiceIndicator;
     const Background = voiceComponents?.VoiceBackground || DefaultVoiceBackground;
     const Transcript = voiceComponents?.VoiceTranscript || DefaultVoiceTranscript;
@@ -416,6 +416,14 @@ 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;
     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.
@@ -476,19 +484,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 +506,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 +526,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}/>
@@ -602,7 +612,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/decide-voice-close.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Classifies why a voice session's WebSocket closed, from the close code
+ * and/or reason string the server sends, into an outcome the caller can act
+ * on without needing to know the raw close-code values itself. Kept as a
+ * pure function so the mapping is unit-testable without loading the
+ * native-bound RealtimeService.
+ */
+export type VoiceCloseReason = 'minutes_exhausted' | 'not_allowed' | 'project_unavailable' | 'other';
+export declare function classifyVoiceClose(event: {
+    code?: number;
+    reason?: string;
+} | null | undefined): VoiceCloseReason;

package/dist/decide-voice-close.js

@@ -0,0 +1,26 @@
+"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;
+    if (code === 4011 || reason === 'VOICE_MINUTES_EXHAUSTED') {
+        return 'minutes_exhausted';
+    }
+    if (code === 4003 || reason === 'VOICE_NOT_ALLOWED') {
+        return 'not_allowed';
+    }
+    // 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

@@ -64,6 +64,11 @@ interface UseVoiceChatOptions {
     apiKey: string;
     userContext?: Record<string, any>;
     contextDescription?: string;
+    /**
+     * BCP 47 locale, forwarded to the neutral message shown when the server
+     * ends the voice session (e.g. `voiceCloseMessage` after minutes run out).
+     */
+    locale?: string;
     onToolSuggested?: VoiceOnToolSuggested;
     toolRenderMode?: VoiceToolRenderMode;
     /**
@@ -119,5 +124,23 @@ interface UseVoiceChatResult {
     acceptNavigationSuggestion: () => void;
     /** Dismiss the pending suggestion without navigating. */
     dismissNavigationSuggestion: () => void;
+    /**
+     * Set when the server closed the voice session for a reason the user
+     * should be told about (currently only `'minutes_exhausted'`). Cleared on
+     * the next `connect()`. `null` in every other case, including a normal
+     * user-initiated `disconnect()`.
+     */
+    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, onToolSuggested, toolRenderMode, getSessionToken, endUserId, endUserData, onNavigationSuggest, }: UseVoiceChatOptions): UseVoiceChatResult;
+export declare function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, locale, onToolSuggested, toolRenderMode, getSessionToken, endUserId, endUserData, onNavigationSuggest, }: UseVoiceChatOptions): UseVoiceChatResult;

package/dist/hooks/useVoiceChat.js

@@ -6,8 +6,30 @@ const react_native_1 = require("react-native");
 const RealtimeService_1 = require("../services/RealtimeService");
 const QafkaAudio_1 = require("../native/QafkaAudio");
 const decide_voice_navigation_1 = require("../decide-voice-navigation");
-function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolSuggested, toolRenderMode = 'upsert', getSessionToken, endUserId, endUserData, onNavigationSuggest, }) {
+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
+ * `services/projectUnavailable.ts` — deliberately generic, no mention of
+ * limits or plans.
+ */
+function voiceUnavailableMessage(locale) {
+    return locale?.toLowerCase().startsWith('tr')
+        ? 'Sesli görüşme şu anda kullanılamıyor. Yazarak sohbete devam edebilirsiniz.'
+        : 'Voice chat is currently unavailable. You can keep chatting by text.';
+}
+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)(() => {
+        localeRef.current = locale;
+    }, [locale]);
     const [transcript, setTranscript] = (0, react_1.useState)('');
     const [userTranscript, setUserTranscript] = (0, react_1.useState)('');
     const [transcriptHistory, setTranscriptHistory] = (0, react_1.useState)([]);
@@ -147,13 +169,29 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
                 setState('listening');
                 return;
             }
-            case 'session.closed':
+            case 'session.closed': {
+                const closeReason = (0, decide_voice_close_1.classifyVoiceClose)({ code: event.code, reason: event.reason });
+                if (closeReason === 'minutes_exhausted') {
+                    // Surface the neutral message and fall back to text chat. The server
+                    // has already closed the socket, so this only tears down local state
+                    // (native audio engine, refs, mute flags) via the same path a
+                    // user-initiated disconnect takes.
+                    setVoiceCloseReason('minutes_exhausted');
+                    setVoiceCloseMessage(voiceUnavailableMessage(localeRef.current));
+                    disconnectRef.current?.();
+                    return;
+                }
+                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({
@@ -392,6 +430,9 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
             return;
         }
         setState('connecting');
+        setSessionEnded(false);
+        setVoiceCloseReason(null);
+        setVoiceCloseMessage(null);
         const service = new RealtimeService_1.RealtimeService(apiUrl, apiKey);
         if (getSessionToken)
             service.setSessionTokenGetter(getSessionToken);
@@ -425,6 +466,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         }
         catch {
             setState('idle');
+            setSessionEnded(true);
             serviceRef.current = null;
         }
     }, [apiUrl, apiKey, handleEvent, userContext, contextDescription, getSessionToken, endUserId, endUserData]);
@@ -434,6 +476,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         await serviceRef.current?.disconnect();
         serviceRef.current = null;
         setState('idle');
+        setSessionEnded(true);
         setTranscript('');
         setUserTranscript('');
         setTranscriptHistory([]);
@@ -449,6 +492,15 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
     (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();
     }, []);
@@ -523,5 +575,10 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         navigationSuggestion,
         acceptNavigationSuggestion,
         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/RealtimeService.d.ts

@@ -3,6 +3,7 @@ export type RealtimeEvent = {
 } | {
     type: 'session.closed';
     reason: string;
+    code?: number;
 } | {
     type: 'response.audio.delta';
     delta: string;

package/dist/services/RealtimeService.js

@@ -145,6 +145,7 @@ class RealtimeService {
                 this.eventHandler?.({
                     type: 'session.closed',
                     reason: event.reason || 'CONNECTION_CLOSED',
+                    code: event.code,
                 });
             };
         });

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qafka/react-native",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "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",