@qafka/react-native 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [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/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, } = 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.

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,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyVoiceClose = classifyVoiceClose;
+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';
+    }
+    if (code === 4010 || reason === 'project_unavailable') {
+        return 'project_unavailable';
+    }
+    return 'other';
+}

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,14 @@ 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;
 }
-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,26 @@ 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");
+/**
+ * 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);
+    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,11 +165,25 @@ 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');
                 setNavigationSuggestion(null);
                 pendingNavDisconnectRef.current = false;
                 return;
+            }
             case 'error':
                 setState('idle');
                 return;
@@ -392,6 +424,8 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
             return;
         }
         setState('connecting');
+        setVoiceCloseReason(null);
+        setVoiceCloseMessage(null);
         const service = new RealtimeService_1.RealtimeService(apiUrl, apiKey);
         if (getSessionToken)
             service.setSessionTokenGetter(getSessionToken);
@@ -523,5 +557,7 @@ function useVoiceChat({ apiUrl, apiKey, userContext, contextDescription, onToolS
         navigationSuggestion,
         acceptNavigationSuggestion,
         dismissNavigationSuggestion,
+        voiceCloseReason,
+        voiceCloseMessage,
     };
 }

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/package.json

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