@qafka/react-native 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [2.6.0] — 2026-09-15
+
+### Added
+
+- Unavailable state: when the assistant for a project is temporarily unavailable, the chat screen now shows a neutral, localized message ("The assistant is currently unavailable." / Turkish when `locale` starts with `tr`) instead of an error. The input is hidden and no error bubble or initialization banner is shown.
+- New `onUnavailable` prop on `<Qafka />`, called when the assistant becomes unavailable (at start-up or mid-conversation). Use it to hide or disable your own entry point to the chat.
+- `SDKStatusType` gains `'unavailable'`, delivered through `onStatusChange` and `QafkaSDK.getStatus()`.
+- Localized greeting: when the `locale` prop is set, the project theme request now includes it, so the greeting and initial message are returned in that language when a translation exists. Without `locale` the request is unchanged.
+
+### Changed
+
+- `QafkaSDK.initialize()` now waits for the project theme request to settle before resolving, so the final status (`'ready'` or `'unavailable'`) is known when it returns. `onError` is not called for the unavailable state.
+- If you `switch` exhaustively over `SDKStatusType` in TypeScript, add a case for `'unavailable'`.
+
+### Documentation
+
+- Clarified how the `locale`, `context` and `contextDescription` props are used, with examples, and documented `onUnavailable` in the tool authoring guide.
+
 ## [2.5.0] — 2026-07-19
 
 ### Added

package/dist/QafkaSDK.d.ts

@@ -13,6 +13,7 @@ export declare class QafkaSDK {
     private conversationManager;
     private navigationHandler;
     private themePrefetchPromise;
+    private themePrefetchError;
     private constructor();
     /**
     * Get singleton instance
@@ -25,8 +26,9 @@ export declare class QafkaSDK {
     /**
     * developer-driven locale (BCP 47 — e.g. "tr", "en", "tr-TR").
     * Forwarded to BackendService so it lands in `sdkContext.locale` on every
-    * outgoing chat request, which the server then echoes into the user-message
-    * context prefix. Same value should drive UI strings on the SDK side.
+    * outgoing chat request — the language the assistant answers in. Explicit
+    * only: never derived from the device language, and it leaves the SDK's own
+    * UI strings untouched.
     *
     * Pass `null` to clear (e.g. when switching back to instructions-default).
     * Calling before initialize() is a no-op; pass `locale` via SDKConfig instead.
@@ -155,6 +157,15 @@ export declare class QafkaSDK {
     */
     getStatus(): SDKStatusType;
     /**
+    * Internal — not part of the documented public surface. Flips the SDK to
+    * the 'unavailable' status mid-session (e.g. a chat request comes back
+    * with `code === 'PROJECT_UNAVAILABLE'` after the project was already
+    * initialized successfully). Notifies the same `onStatusChange` listener
+    * `initialize()` uses, so `useSDK` reacts identically regardless of
+    * whether unavailability was detected at init time or mid-session.
+    */
+    markUnavailable(): void;
+    /**
     * Get SDK configuration
     */
     getConfig(): SDKConfig | null;

package/dist/QafkaSDK.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSDK = exports.QafkaSDK = void 0;
 const storage_1 = require("./services/storage");
 const BackendService_1 = require("./services/BackendService");
+const projectUnavailable_1 = require("./services/projectUnavailable");
 const AttestationManager_1 = require("./services/AttestationManager");
 const ConversationManager_1 = require("./services/ConversationManager");
 const NavigationHandler_1 = require("./services/NavigationHandler");
@@ -24,6 +25,11 @@ class QafkaSDK {
     // ChatPage can render the branded greeting without waiting for SDK ready.
     // See `useProjectTheme` which awaits this promise.
     themePrefetchPromise = null;
+    // Captured alongside themePrefetchPromise (which swallows its rejection so
+    // useProjectTheme always gets a settled promise). initialize() inspects
+    // this after the prefetch settles to decide whether the final status is
+    // 'ready' or 'unavailable'.
+    themePrefetchError = null;
     constructor() { }
     /**
     * Get singleton instance
@@ -78,7 +84,10 @@ class QafkaSDK {
             // needs are not ready yet — firing the prefetch now would fail, blank out
             // the greeting, and need a retry. Deferred to after init below.
             if (apiKey) {
-                this.themePrefetchPromise = this.prefetchAndCacheTheme().catch(() => null);
+                this.themePrefetchPromise = this.prefetchAndCacheTheme().catch((err) => {
+                    this.themePrefetchError = err;
+                    return null;
+                });
             }
             // Save config to storage
             await storage_1.storage.setItem('@qafka/config', JSON.stringify(config));
@@ -103,7 +112,10 @@ class QafkaSDK {
                 // credentials it needs and the prefetch will succeed on first try,
                 // hydrating useProjectTheme before the chat surface paints.
                 if (!apiKey && !this.themePrefetchPromise) {
-                    this.themePrefetchPromise = this.prefetchAndCacheTheme().catch(() => null);
+                    this.themePrefetchPromise = this.prefetchAndCacheTheme().catch((err) => {
+                        this.themePrefetchError = err;
+                        return null;
+                    });
                 }
             }
             catch (error) {
@@ -119,9 +131,19 @@ class QafkaSDK {
                     throw error;
                 }
             }
-            this.status = 'ready';
+            // 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).
+            if (this.themePrefetchPromise) {
+                await this.themePrefetchPromise;
+            }
+            this.status = this.themePrefetchError instanceof projectUnavailable_1.ProjectUnavailableError
+                ? 'unavailable'
+                : 'ready';
             if (config.onStatusChange) {
-                config.onStatusChange('ready');
+                config.onStatusChange(this.status);
             }
         }
         catch (error) {
@@ -146,8 +168,9 @@ class QafkaSDK {
     /**
     * developer-driven locale (BCP 47 — e.g. "tr", "en", "tr-TR").
     * Forwarded to BackendService so it lands in `sdkContext.locale` on every
-    * outgoing chat request, which the server then echoes into the user-message
-    * context prefix. Same value should drive UI strings on the SDK side.
+    * outgoing chat request — the language the assistant answers in. Explicit
+    * only: never derived from the device language, and it leaves the SDK's own
+    * UI strings untouched.
     *
     * Pass `null` to clear (e.g. when switching back to instructions-default).
     * Calling before initialize() is a no-op; pass `locale` via SDKConfig instead.
@@ -444,6 +467,20 @@ class QafkaSDK {
         return this.status;
     }
     /**
+    * Internal — not part of the documented public surface. Flips the SDK to
+    * the 'unavailable' status mid-session (e.g. a chat request comes back
+    * with `code === 'PROJECT_UNAVAILABLE'` after the project was already
+    * initialized successfully). Notifies the same `onStatusChange` listener
+    * `initialize()` uses, so `useSDK` reacts identically regardless of
+    * whether unavailability was detected at init time or mid-session.
+    */
+    markUnavailable() {
+        this.status = 'unavailable';
+        if (this.config?.onStatusChange) {
+            this.config.onStatusChange('unavailable');
+        }
+    }
+    /**
     * Get SDK configuration
     */
     getConfig() {
@@ -480,6 +517,7 @@ class QafkaSDK {
         this.subProjectId = null;
         this.config = null;
         this.themePrefetchPromise = null;
+        this.themePrefetchError = null;
         this.status = 'uninitialized';
         // Only clear the shared singleton slot when WE are still the current
         // instance. An outgoing component unmounting must not null a newer

package/dist/components/ChatPage.d.ts

@@ -19,6 +19,12 @@ export interface ChatPageProps {
     } | null;
     sdkReady: boolean;
     sdkError: string | null;
+    /** True when the project is unavailable (suspended). Replaces the whole
+    * chat surface (messages, composer, error banner) with a neutral, centered
+    * message instead. */
+    unavailable?: boolean;
+    /** Forwarded to `unavailableMessage()` for the neutral copy above. */
+    locale?: string;
     theme: Theme;
     handleSend: (text: string) => void;
     handleActionClick: (action: any) => void;
@@ -41,4 +47,4 @@ export interface ChatPageProps {
     cardHostCallbacks?: import('../cards/cta/types').CardCTAHostCallbacks;
     cardLifecycle?: import('../cards/cta/types').CardCTALifecycle;
 }
-export declare function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, toolStatus, sdkReady, sdkError, theme, handleSend, handleActionClick, handleExternalSuggestionPress, flatListRef, placeholder, maxMessageLength, showTimestamps, greetingMessage, apiGreeting, isInitialMessageEnabled, initialMessageText, componentRegistry, onBack, onClose, BackComponent, CloseComponent, NavigationButtonComponent, cardHostCallbacks, cardLifecycle, }: ChatPageProps): React.JSX.Element;
+export declare function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, toolStatus, sdkReady, sdkError, unavailable, locale, theme, handleSend, handleActionClick, handleExternalSuggestionPress, flatListRef, placeholder, maxMessageLength, showTimestamps, greetingMessage, apiGreeting, isInitialMessageEnabled, initialMessageText, componentRegistry, onBack, onClose, BackComponent, CloseComponent, NavigationButtonComponent, cardHostCallbacks, cardLifecycle, }: ChatPageProps): React.JSX.Element;

package/dist/components/ChatPage.js

@@ -11,7 +11,8 @@ const InputArea_1 = require("./InputArea");
 const TypingIndicator_1 = require("./TypingIndicator");
 const ToolStatusPill_1 = require("./ToolStatusPill");
 const Qafka_styles_1 = require("./Qafka.styles");
-function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, toolStatus, sdkReady, sdkError, theme, handleSend, handleActionClick, handleExternalSuggestionPress, flatListRef, placeholder, maxMessageLength, showTimestamps, greetingMessage, apiGreeting, isInitialMessageEnabled, initialMessageText, componentRegistry, onBack, onClose, BackComponent, CloseComponent, NavigationButtonComponent, cardHostCallbacks, cardLifecycle, }) {
+const projectUnavailable_1 = require("../services/projectUnavailable");
+function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, toolStatus, sdkReady, sdkError, unavailable, locale, theme, handleSend, handleActionClick, handleExternalSuggestionPress, flatListRef, placeholder, maxMessageLength, showTimestamps, greetingMessage, apiGreeting, isInitialMessageEnabled, initialMessageText, componentRegistry, onBack, onClose, BackComponent, CloseComponent, NavigationButtonComponent, cardHostCallbacks, cardLifecycle, }) {
     const styles = (0, Qafka_styles_1.getWidgetStyles)(theme);
     const renderMessage = ({ item }) => (<MessageBubble_1.MessageBubble message={item.text || item.content} role={item.role === 'system' ? 'assistant' : item.role} timestamp={new Date(item.timestamp)} theme={theme} showTimestamp={showTimestamps} actions={item.actions} onActionPress={handleActionClick} componentRegistry={componentRegistry} toolDefinition={item.toolResponse?.tool} toolResultData={item.toolResponse?.data} NavigationButtonComponent={NavigationButtonComponent} actionResults={item.actionResults} completedSteps={item.completedSteps} externalSuggestions={item.externalSuggestions} onExternalPress={handleExternalSuggestionPress} card={item.card} cardHostCallbacks={cardHostCallbacks} cardLifecycle={cardLifecycle}/>);
     const renderEmpty = () => {
@@ -54,6 +55,15 @@ function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, tool
  </react_native_1.View>
  </react_native_1.View>)}
 
+ {unavailable ? (
+        /* Project unavailable (suspended): replace the whole chat surface —
+        messages, composer, error banner — with a neutral, centered message.
+        No "Something went wrong" bubble, no input, no typing indicator. */
+        <react_native_1.View style={[styles.emptyStateStyle, { flex: 1 }]}>
+ <react_native_1.Text style={styles.emptyStateTextStyle}>
+ {(0, projectUnavailable_1.unavailableMessage)(locale)}
+ </react_native_1.Text>
+ </react_native_1.View>) : (<>
  {/* Error banner */}
  {sdkError && (<react_native_1.View style={styles.errorStyle}>
  <react_native_1.Text style={styles.errorTextStyle}>{sdkError}</react_native_1.Text>
@@ -63,10 +73,10 @@ function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, tool
  <react_native_1.FlatList ref={flatListRef} data={displayMessages} renderItem={renderMessage} keyExtractor={(item) => item.id} style={{ flex: 1, flexGrow: 1, flexShrink: 1 }} contentContainerStyle={styles.messageListStyle} ListEmptyComponent={renderEmpty} showsVerticalScrollIndicator={false} keyboardShouldPersistTaps="handled" ListFooterComponent={toolStatus ? (<react_native_1.View style={{ paddingHorizontal: 8, paddingTop: 4, alignItems: 'flex-start' }}>
  <ToolStatusPill_1.ToolStatusPill message={toolStatus.message} theme={theme}/>
  </react_native_1.View>) : null} onContentSizeChange={() => {
-            if (displayMessages.length > 0) {
-                flatListRef.current?.scrollToEnd({ animated: true });
-            }
-        }}/>
+                if (displayMessages.length > 0) {
+                    flatListRef.current?.scrollToEnd({ animated: true });
+                }
+            }}/>
 
  {/* Typing Indicator */}
  {isTyping && !streamingMessage && (<react_native_1.View style={styles.typingIndicatorContainer}>
@@ -74,11 +84,12 @@ function ChatPage({ displayMessages, isTyping, isSending, streamingMessage, tool
  </react_native_1.View>)}
 
  {/* Tool Status Pill now renders inside the list (ListFooterComponent)
-        so it sits directly under the last message and scrolls with it. */}
+            so it sits directly under the last message and scrolls with it. */}
 
  {/* Input Area — hidden until SDK is ready so users can't type a message
-        that would be rejected by an un-attested send. TypingIndicator in the
-        empty state carries the "still preparing" signal. */}
+            that would be rejected by an un-attested send. TypingIndicator in the
+            empty state carries the "still preparing" signal. */}
  {sdkReady && (<InputArea_1.InputArea theme={theme} placeholder={placeholder} onSend={handleSend} isSending={isSending} maxLength={maxMessageLength}/>)}
+ </>)}
  </>);
 }

package/dist/components/Qafka.js

@@ -87,10 +87,10 @@ 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, 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, 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, error: sdkError, resolvedApiKey, resolvedApiUrl } = (0, useSDK_1.useSDK)({
+    const { sdkReady, unavailable, error: sdkError, resolvedApiKey, resolvedApiUrl } = (0, useSDK_1.useSDK)({
         apiUrl: apiUrlProp,
         devConfig,
         subProjectId,
@@ -98,6 +98,7 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
         locale,
         onReady,
         onError,
+        onUnavailable,
     });
     const { theme, isLoadingTheme, greeting: apiGreeting, initialMessage: initialMessageText, isInitialMessageEnabled, voiceEnabled, } = (0, useProjectTheme_1.useProjectTheme)({
         sdkReady,
@@ -432,6 +433,8 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
         toolStatus,
         sdkReady,
         sdkError,
+        unavailable,
+        locale,
         theme,
         handleSend,
         handleActionClick,

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

@@ -283,14 +283,14 @@ export interface QafkaProps {
     /**
     * BCP 47 locale (e.g. "tr", "en", "tr-TR").
     *
-    * Drives UI strings (placeholder, buttons, dashboard-supplied multi-locale
-    * greeting) and is forwarded to the backend as part of `sdkContext.locale`.
-    * Pair with the server-side language priority rule: when set, the AI
-    * answers in this locale unless project instructions explicitly demand
-    * another language.
+    * The language your app declares the user speaks. Forwarded to the backend
+    * as `sdkContext.locale`: when set, the assistant answers in this language
+    * unless the project's own instructions demand another one. It does not
+    * change the SDK's built-in UI strings.
     *
-    * Leave undefined to fall back to whatever language the project
-    * instructions are written in.
+    * Explicit only — the SDK never reads the device language for this. Leave
+    * undefined when your app has no language choice of its own, and the
+    * project's configured language decides.
     *
     * @example "tr"
     * @example "en-US"
@@ -364,16 +364,29 @@ export interface QafkaProps {
      */
     endUserData?: Record<string, unknown>;
     /**
-    * Context object for Tool Registry.
-    * Provides runtime context to match and execute tools.
-    * @example { userId: '456', selectedItemId: '123' }
-    */
+     * Runtime facts the assistant may use to personalize answers: the signed-in
+     * user's first name, their selected store or branch, account state, an
+     * active promotion's progress — whatever the AI should know about THIS user
+     * right now.
+     *
+     * Every key is visible to the AI (flattened into the prompt as `key: value`
+     * lines) and available to tool parameters with `source: 'context'`. Because
+     * these keys DO reach the prompt, identity data the AI should not see
+     * belongs in `endUserData` instead — that lane is never sent to the LLM.
+     *
+     * When a value has no meaningful state, send an explicit "empty" shape
+     * rather than omitting the key — an absent key gives the AI nothing to
+     * reason about, so it answers "I don't know".
+     *
+     * @example { firstName: 'Ada', selectedStoreId: '123', activeSession: { active: false } }
+     */
     context?: Record<string, any>;
     /**
-    * Context description for the AI.
-    * Helps the AI understand what the context keys mean.
-    * @example "User is on the settings screen"
-    */
+     * One human-readable sentence describing the screen the user is currently
+     * on. Kept separate from `context`: it describes the user's LOCATION, not a
+     * fact about them, and the prompt places it above the context lines.
+     * @example "User is on the settings screen"
+     */
     contextDescription?: string;
     /**
     * Custom component registry for Tool Registry responses.
@@ -422,6 +435,14 @@ export interface QafkaProps {
     */
     onError?: (error: Error) => void;
     /**
+    * Callback when the project becomes unavailable (suspended). The chat
+    * screen stays mounted and shows a neutral message instead of the normal
+    * chat surface; use this to hide your own entry point (launcher button,
+    * nav item, ...) if you don't want users opening it in this state. Not
+    * treated as an error — `onError` is not also called for this transition.
+    */
+    onUnavailable?: () => void;
+    /**
     * Callback when navigation is suggested (always triggered)
     */
     onNavigationSuggest?: (suggestion: NavigationSuggestion) => void;

package/dist/hooks/useChatMessages.js

@@ -534,6 +534,14 @@ 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') {
+            QafkaSDK_1.QafkaSDK.getInstance().markUnavailable();
+            return;
+        }
         const errorMessage = err.message || 'Unknown error';
         onError?.(err instanceof Error ? err : new Error(errorMessage));
         // Default fallback bubble. Apps that want a localized or custom error

package/dist/hooks/useSDK.d.ts

@@ -10,10 +10,18 @@ export interface UseSDKOptions {
     locale?: string;
     onReady?: () => void;
     onError?: (error: Error) => void;
+    /**
+     * Fired when the project is unavailable (suspended). Mutually exclusive
+     * with `onError`/`onReady` for this transition — the SDK treats
+     * unavailability as an expected, recoverable state rather than a failure.
+     */
+    onUnavailable?: () => void;
     devConfig?: unknown;
 }
 export interface UseSDKResult {
     sdkReady: boolean;
+    /** True once the SDK has determined the project is unavailable (suspended). */
+    unavailable: boolean;
     error: string | null;
     /**
      * Dev-only: the resolved developmentKey from the consumer dev config — the
@@ -31,4 +39,4 @@ export interface UseSDKResult {
 /**
  * Custom hook for managing SDK initialization and lifecycle
  */
-export declare const useSDK: ({ apiUrl, subProjectId, projectId, locale, onReady, onError, devConfig, }: UseSDKOptions) => UseSDKResult;
+export declare const useSDK: ({ apiUrl, subProjectId, projectId, locale, onReady, onError, onUnavailable, devConfig, }: UseSDKOptions) => UseSDKResult;

package/dist/hooks/useSDK.js

@@ -9,15 +9,18 @@ const resolve_runtime_config_source_1 = require("../resolve-runtime-config-sourc
 /**
  * Custom hook for managing SDK initialization and lifecycle
  */
-const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, devConfig, }) => {
+const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, onUnavailable, devConfig, }) => {
     const [sdkReady, setSdkReady] = (0, react_1.useState)(false);
+    const [unavailable, setUnavailable] = (0, react_1.useState)(false);
     const [error, setError] = (0, react_1.useState)(null);
     const [resolvedApiKey, setResolvedApiKey] = (0, react_1.useState)(null);
     const [resolvedApiUrl, setResolvedApiUrl] = (0, react_1.useState)(apiUrl);
     const onReadyRef = (0, react_1.useRef)(onReady);
     const onErrorRef = (0, react_1.useRef)(onError);
+    const onUnavailableRef = (0, react_1.useRef)(onUnavailable);
     onReadyRef.current = onReady;
     onErrorRef.current = onError;
+    onUnavailableRef.current = onUnavailable;
     const initializeSDK = async () => {
         if (!projectId) {
             const err = new Error('Qafka: `projectId` prop is required.');
@@ -54,9 +57,17 @@ const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, dev
                 locale,
                 onStatusChange: (status) => {
                     if (status === 'ready') {
+                        setUnavailable(false);
                         setSdkReady(true);
                         onReadyRef.current?.();
                     }
+                    else if (status === 'unavailable') {
+                        // Unavailability is an expected, recoverable state — not a
+                        // failure — so no onError/sdkError here, only onUnavailable.
+                        setSdkReady(false);
+                        setUnavailable(true);
+                        onUnavailableRef.current?.();
+                    }
                     else if (status === 'error') {
                         setError('Failed to initialize SDK');
                         onErrorRef.current?.(new Error('SDK initialization failed'));
@@ -82,10 +93,12 @@ const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, dev
     (0, react_1.useEffect)(() => {
         const sdk = QafkaSDK_1.QafkaSDK.getInstance();
         setSdkReady(false);
+        setUnavailable(false);
         setError(null);
         initializeSDK();
         return () => {
             setSdkReady(false);
+            setUnavailable(false);
             sdk.destroy();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -99,6 +112,7 @@ const useSDK = ({ apiUrl, subProjectId, projectId, locale, onReady, onError, dev
     }, [locale, sdkReady]);
     return {
         sdkReady,
+        unavailable,
         error,
         resolvedApiKey,
         resolvedApiUrl,

package/dist/services/BackendService.d.ts

@@ -103,7 +103,14 @@ export declare class BackendService {
     */
     deleteConversation(sessionId: string): Promise<void>;
     /**
-    * Get project theme
+    * Get project theme.
+    *
+    * Sends the explicit locale, when the host set one, so the server can answer
+    * with its translation of the project's greeting / initial message instead of
+    * the language they were authored in. Same source as `sdkContext.locale`: the
+    * `<Qafka locale>` prop only, never a device language. Unset ⇒ no param ⇒ the
+    * request is identical to the one earlier SDK versions send, and the server
+    * reads a missing param as "no signal".
     */
     getTheme(): Promise<any>;
     /**

package/dist/services/BackendService.js

@@ -4,6 +4,7 @@ exports.BackendService = void 0;
 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");
 /**
  * Backend API Service using native fetch
  */
@@ -25,8 +26,10 @@ class BackendService {
     attestationManager = null;
     refreshing = null;
     // locale is only added to sdkContext when explicitly set by the
-    // developer via <Qafka locale="..." />. Drives both UI strings and the
-    // user-message context prefix on the server.
+    // developer via <Qafka locale="..." />. There is no device/system-language
+    // fallback on purpose: the server reads this field as the language the USER
+    // writes in, and a device default would state that for every host app that
+    // never made the choice. The SDK's own UI strings are unaffected by it.
     locale = null;
     // Tool Data Channel
     onToolDataRequested = null;
@@ -273,6 +276,12 @@ class BackendService {
             const errorCode = errorData.error || 'UNKNOWN_ERROR';
             const errorMessage = errorData.message || response.statusText;
             const hint = errorData.hint || '';
+            // Project suspended — a distinct signal from the other 403 branches
+            // below, callers across the SDK branch on `ProjectUnavailableError` /
+            // `code === 'PROJECT_UNAVAILABLE'` rather than parsing message strings.
+            if ((0, projectUnavailable_1.isProjectUnavailable)(response.status, errorData)) {
+                throw new projectUnavailable_1.ProjectUnavailableError(errorMessage);
+            }
             // 401: Unauthorized (Invalid/Missing API Key)
             if (response.status === 401) {
                 if (errorCode === 'MISSING_API_KEY') {
@@ -399,18 +408,35 @@ class BackendService {
         }
     }
     /**
-    * Get project theme
+    * Get project theme.
+    *
+    * Sends the explicit locale, when the host set one, so the server can answer
+    * with its translation of the project's greeting / initial message instead of
+    * the language they were authored in. Same source as `sdkContext.locale`: the
+    * `<Qafka locale>` prop only, never a device language. Unset ⇒ no param ⇒ the
+    * request is identical to the one earlier SDK versions send, and the server
+    * reads a missing param as "no signal".
     */
     async getTheme() {
         try {
             const cleanApiUrl = this.baseURL.replace(/\/api\/v1\/?$/, '');
-            const queryParams = this.subProjectId
-                ? `?subProjectId=${encodeURIComponent(this.subProjectId)}`
-                : '';
+            const query = [];
+            if (this.subProjectId) {
+                query.push(`subProjectId=${encodeURIComponent(this.subProjectId)}`);
+            }
+            if (this.locale) {
+                query.push(`locale=${encodeURIComponent(this.locale)}`);
+            }
+            const queryParams = query.length > 0 ? `?${query.join('&')}` : '';
             const response = await this.fetchWithTimeout(`${cleanApiUrl}/api/v1/public/projects/chat-theme${queryParams}`, { method: 'GET' });
             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) {
+                throw error;
+            }
             throw new Error(error.message || 'Failed to fetch theme');
         }
     }
@@ -645,13 +671,21 @@ class BackendService {
                     });
                 }
                 else {
-                    let serverMessage;
+                    let parsedBody;
                     try {
-                        serverMessage = JSON.parse(xhr.responseText)?.message;
+                        parsedBody = JSON.parse(xhr.responseText);
                     }
                     catch {
                         // non-JSON error body; fall through to a status-based message
                     }
+                    const serverMessage = parsedBody?.message;
+                    if ((0, projectUnavailable_1.isProjectUnavailable)(xhr.status, parsedBody)) {
+                        const unavailableErr = new Error(serverMessage || 'The assistant is currently unavailable.');
+                        unavailableErr.code = 'PROJECT_UNAVAILABLE';
+                        unavailableErr.status = xhr.status;
+                        onError(unavailableErr);
+                        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/projectUnavailable.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared helpers for the "project unavailable" state: the backend answers
+ * with HTTP 403 `{ error: 'project_unavailable' }` when the project (or its
+ * parent) is suspended. The chat screen stays mounted but shows a neutral
+ * message instead of the normal chat surface or an error bubble.
+ */
+/**
+ * True when a response is the specific "project unavailable" signal, as
+ * opposed to any other 403 (bundle id, platform, permission, ...).
+ */
+export declare function isProjectUnavailable(status: number, body: unknown): boolean;
+/**
+ * Thrown by the transport layer when a request fails because the project is
+ * unavailable. Callers branch on `code`, not `instanceof`, where they only
+ * have a plain error (e.g. across the streaming/XHR boundary).
+ */
+export declare class ProjectUnavailableError extends Error {
+    code: string;
+    constructor(message?: string);
+}
+/**
+ * Neutral, locale-aware copy shown in place of the chat surface when the
+ * project is unavailable. Deliberately generic — no mention of payment,
+ * plans, or Qafka — so it reads the same regardless of the underlying cause.
+ */
+export declare function unavailableMessage(locale?: string): string;

package/dist/services/projectUnavailable.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Shared helpers for the "project unavailable" state: the backend answers
+ * with HTTP 403 `{ error: 'project_unavailable' }` when the project (or its
+ * parent) is suspended. The chat screen stays mounted but shows a neutral
+ * message instead of the normal chat surface or an error bubble.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProjectUnavailableError = void 0;
+exports.isProjectUnavailable = isProjectUnavailable;
+exports.unavailableMessage = unavailableMessage;
+/**
+ * True when a response is the specific "project unavailable" signal, as
+ * opposed to any other 403 (bundle id, platform, permission, ...).
+ */
+function isProjectUnavailable(status, body) {
+    if (status !== 403)
+        return false;
+    if (!body || typeof body !== 'object')
+        return false;
+    return body.error === 'project_unavailable';
+}
+/**
+ * Thrown by the transport layer when a request fails because the project is
+ * unavailable. Callers branch on `code`, not `instanceof`, where they only
+ * have a plain error (e.g. across the streaming/XHR boundary).
+ */
+class ProjectUnavailableError extends Error {
+    code = 'PROJECT_UNAVAILABLE';
+    constructor(message = 'The assistant is currently unavailable.') {
+        super(message);
+        this.name = 'ProjectUnavailableError';
+        Object.setPrototypeOf(this, ProjectUnavailableError.prototype);
+    }
+}
+exports.ProjectUnavailableError = ProjectUnavailableError;
+/**
+ * Neutral, locale-aware copy shown in place of the chat surface when the
+ * project is unavailable. Deliberately generic — no mention of payment,
+ * plans, or Qafka — so it reads the same regardless of the underlying cause.
+ */
+function unavailableMessage(locale) {
+    return locale?.toLowerCase().startsWith('tr')
+        ? 'Asistan şu anda hizmet verememektedir.'
+        : 'The assistant is currently unavailable.';
+}

package/dist/types/sdk.d.ts

@@ -23,9 +23,10 @@ export interface SDKConfig {
     /** Request timeout in ms. */
     timeout?: number;
     /**
-    * BCP 47 locale (e.g. "tr", "en", "tr-TR"). When set, the SDK
-    * forwards it as `sdkContext.locale` on every chat request and uses it
-    * for UI strings.
+    * BCP 47 locale (e.g. "tr", "en", "tr-TR"). When set, the SDK forwards it
+    * as `sdkContext.locale` on every chat request — the language the assistant
+    * answers in. Explicit only: never derived from the device language, and it
+    * does not change the SDK's own UI strings.
     */
     locale?: string;
     onStatusChange?: (status: SDKStatusType) => void;
@@ -35,4 +36,4 @@ export interface SDKConfig {
 /**
  * SDK status type
  */
-export type SDKStatusType = 'uninitialized' | 'initializing' | 'ready' | 'error';
+export type SDKStatusType = 'uninitialized' | 'initializing' | 'ready' | 'unavailable' | 'error';

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

@@ -278,11 +278,26 @@ to handle in code. It shows a small set of key/value chips (or routes text to th
 You may optionally restyle the chips via `voiceComponents.dataChipList` / `voiceComponents.dataChip`.
 
 ### Useful context props
-- **`context`** + **`contextDescription`** — a runtime data bag passed to the AI, with a
-  description of what its keys mean. (Tool parameters with `source: 'context'` read from here.)
-- **`endUserData`** — non-LLM metadata about the user (≤8KB).
+- **`context`** — runtime facts the AI may use to personalize answers (first name, selected
+  store, account state). Every key reaches the AI prompt; tool parameters with
+  `source: 'context'` also read from here. For a value with no meaningful state, send an
+  explicit "empty" shape rather than omitting the key.
+- **`contextDescription`** — one sentence describing the screen the user is currently on
+  (their location, not a fact about them; shown to the AI above the context lines).
+- **`endUserData`** — non-LLM metadata about the user (≤8KB). Never reaches the AI prompt —
+  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 —
+  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);
+
+  <Qafka onUnavailable={() => setChatAvailable(false)} />
+  {chatAvailable && <LauncherButton onPress={openChat} />}
+  ```
 
 ---
 

package/package.json

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