@qafka/react-native 2.4.1 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [2.5.0] — 2026-07-19
+
+### Added
+
+- Image generation: a new `generateImage()` method creates an image from a text description, or reframes one or more reference images to a target aspect ratio or exact pixel size without stretching or distortion. Results can be returned as base64, a signed time-limited URL, or both, and multiple variants can be requested in a single call. Higher-quality `pro` output is available when it is enabled on your plan. See the "Image Generation" section of the README for the full API, response shape, and error handling.
+
+## [2.4.2] — 2026-06-22
+
+### Fixed
+
+- Voice could fail to connect (the orb stayed on the connecting/waiting state) in apps that did not pass an explicit `apiUrl`. The realtime WebSocket now falls back to the same default backend host as the REST/chat client, instead of building a host-less relative URL that could never complete its handshake. Apps relying on the default backend no longer need to set `apiUrl` just to make voice work.
+
 ## [2.4.1] — 2026-06-21
 
 ### Fixed

package/README.md

@@ -87,6 +87,78 @@ Pass `projectId` when your app has more than one registered project:
 <Qafka projectId="proj_abc123" />
 ```
 
+## Image Generation
+
+Generate images from text descriptions or reframe reference images to target aspect ratios and sizes without distortion. The SDK must be initialized before calling this method.
+
+```tsx
+import { getSDK } from '@qafka/react-native';
+
+const result = await getSDK().generateImage({
+  description: 'product photo reframed to 16:9 landscape',
+  referenceImage: 'https://example.com/photo.jpg',
+  aspectRatio: '16:9',
+  quality: 'standard',
+  n: 1,
+});
+```
+
+### Parameters
+
+| Param | Type | Required | Notes |
+|-------|------|----------|-------|
+| `description` | string | Yes | Text description of the desired image or transformation. |
+| `referenceImage` | string \| string[] | No | Base64 data-URI, URL, or array of either. Used to guide or reframe the output. |
+| `aspectRatio` | string | No | Free-form ratio, e.g. `"16:9"`, `"7:3"`, `"1:1"`. Ignored if `size` is set. |
+| `size` | `{ width: number; height: number }` | No | Exact pixel dimensions. Overrides `aspectRatio`. |
+| `quality` | `'standard' \| 'pro'` | No | Default: `'standard'`. `'pro'` requires image generation pro to be enabled on your plan. |
+| `responseType` | `'base64' \| 'url' \| 'both'` | No | Default: `'base64'`. `'url'` returns a signed, time-limited link; `'both'` returns both. |
+| `n` | number | No | Number of variants to generate. Default: `1`. When `n > 1`, result is an array. |
+
+### Result
+
+Each generated image is an object with:
+
+```tsx
+{
+  base64?: string;        // Returned when responseType includes 'base64'
+  url?: string;           // Signed link, time-limited. Returned when responseType includes 'url'
+  expiresAt?: string;     // ISO 8601 timestamp. Present when url is returned
+  mimeType: string;       // e.g. 'image/png'
+}
+```
+
+When `n > 1`, the result is an array of such objects.
+
+### Example
+
+Reframe an uploaded product photo to a banner size and fetch the result as a base64 image:
+
+```tsx
+try {
+  const result = await getSDK().generateImage({
+    description: 'High-quality product banner, maintaining all product details',
+    referenceImage: productPhotoBase64,
+    size: { width: 1200, height: 300 },
+    responseType: 'base64',
+  });
+  
+  setGeneratedImage(result.base64);
+} catch (err) {
+  if (err.code === 'not_entitled') {
+    showAlert('Image generation is not enabled on your plan.');
+  } else if (err.code === 'rate_limited') {
+    showAlert('Too many requests. Please try again later.');
+  } else if (err.code === 'content_filtered') {
+    showAlert('The description or reference image was filtered for policy reasons.');
+  } else if (err.code === 'invalid_reference') {
+    showAlert('The reference image could not be processed.');
+  } else {
+    showAlert('Image generation failed. Please try again.');
+  }
+}
+```
+
 ## Documentation
 
 Full guides, API reference, theming, voice mode, tools, and advanced configuration:

package/dist/QafkaSDK.d.ts

@@ -1,4 +1,4 @@
-import { SDKConfig, SDKStatusType, ChatMessage, ChatResponse } from './types';
+import { SDKConfig, SDKStatusType, ChatMessage, ChatResponse, GenerateImageParams, GenerateImageResult } from './types';
 /**
  * QafkaSDK - Main SDK class
  * Provides AI-powered conversational interface for React Native apps
@@ -131,6 +131,10 @@ export declare class QafkaSDK {
         type: string;
     }, conversationId?: string): Promise<any>;
     /**
+    * Generate an image based on a description
+    */
+    generateImage(params: GenerateImageParams): Promise<GenerateImageResult>;
+    /**
     * Get project theme configuration
     */
     getProjectTheme(): Promise<any>;

package/dist/QafkaSDK.js

@@ -6,6 +6,7 @@ const BackendService_1 = require("./services/BackendService");
 const AttestationManager_1 = require("./services/AttestationManager");
 const ConversationManager_1 = require("./services/ConversationManager");
 const NavigationHandler_1 = require("./services/NavigationHandler");
+const constants_1 = require("./constants");
 /**
  * QafkaSDK - Main SDK class
  * Provides AI-powered conversational interface for React Native apps
@@ -85,7 +86,7 @@ class QafkaSDK {
             await this.conversationManager.initialize();
             this.navigationHandler = new NavigationHandler_1.NavigationHandler(config.navigationRef);
             // Initialize device attestation
-            const rawUrl = (config.apiUrl || 'https://api.qafka.com/api/v1').replace(/\/$/, '');
+            const rawUrl = (config.apiUrl || `${constants_1.DEFAULT_API_BASE}/api/v1`).replace(/\/$/, '');
             const attestApiUrl = rawUrl.includes('/api/v1') ? rawUrl : `${rawUrl}/api/v1`;
             this.attestationManager = new AttestationManager_1.AttestationManager({
                 apiUrl: attestApiUrl,
@@ -382,6 +383,21 @@ class QafkaSDK {
         return this.backendService.uploadFile(toolId, file, conversationId);
     }
     /**
+    * Generate an image based on a description
+    */
+    async generateImage(params) {
+        if (this.status !== 'ready') {
+            throw new Error('SDK not initialized. Call initialize() first.');
+        }
+        if (!params?.description?.trim()) {
+            throw new Error('description cannot be empty');
+        }
+        if (!this.backendService) {
+            throw new Error('Backend service not initialized');
+        }
+        return this.backendService.generateImage(params);
+    }
+    /**
     * Get project theme configuration
     */
     async getProjectTheme() {

package/dist/components/Qafka.js

@@ -49,6 +49,7 @@ const validate_end_user_1 = require("../validate-end-user");
 const ChatPage_1 = require("./ChatPage");
 const VoicePage_1 = require("./VoicePage");
 const useVoiceChat_1 = require("../hooks/useVoiceChat");
+const constants_1 = require("../constants");
 const { width: SCREEN_WIDTH } = react_native_1.Dimensions.get('window');
 /**
  * Qafka Component
@@ -126,10 +127,10 @@ exports.Qafka = (0, react_1.forwardRef)(function Qafka({ style, apiUrl: apiUrlPr
         debounceMs: 500,
     });
     const voiceChat = (0, useVoiceChat_1.useVoiceChat)({
-        // Voice WebSocket still uses apiKey-based auth. In dev, the resolved
-        // developmentKey from qafka.config.js flows through. In production, this
-        // is null and voice will fail at WS handshake.
-        apiUrl: resolvedApiUrl || apiUrlProp || '',
+        // Voice realtime WebSocket. Fall back to the shared default backend host so
+        // the WS URL never resolves host-less (an empty apiUrl produced a relative
+        // `/v1/realtime` URL → handshake failure). Mirrors the REST client default.
+        apiUrl: resolvedApiUrl || apiUrlProp || constants_1.DEFAULT_API_BASE,
         apiKey: resolvedApiKey || '',
         userContext: currentContext,
         contextDescription,

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

@@ -8,10 +8,11 @@ import type { RuntimeConfig } from '../runtime-config-loader';
 /**
  * Augmentation hook for consumer-side projectId literal types.
  *
- * The Qafka CLI generates a `qafka.config.d.ts` file alongside
- * `qafka.config.js` whenever it writes the runtime config. That `.d.ts`
- * augments this interface with the consumer's project ids as keys —
- * giving `<Qafka projectId="..." />` autocomplete + typo validation.
+ * The Qafka CLI generates a `qafka.config.d.ts` file at the consumer
+ * project root whenever it writes the runtime config; the consumer's
+ * tsconfig file scan picks it up. That `.d.ts` augments this interface
+ * with the consumer's project ids as keys — giving
+ * `<Qafka projectId="..." />` autocomplete + typo validation.
  *
  * When the augmentation is absent (fresh project, `qafka init` not yet
  * run), `keyof QafkaProjectIds` is `never` and `ProjectIdOf` falls back

package/dist/constants.d.ts

@@ -3,6 +3,16 @@
  */
 export declare const API_VERSION = "v1";
 export declare const DEFAULT_API_TIMEOUT = 30000;
+/**
+ * Default Qafka backend base host (scheme + host only).
+ *
+ * The REST client appends `/api/v1` and the realtime voice client appends
+ * `/v1/realtime`, so this holds the bare base. Used as the fallback when neither
+ * an explicit `apiUrl` prop nor a runtime-config `apiUrl` is provided — keeps the
+ * REST and voice transports pointed at the same host instead of one silently
+ * defaulting while the other resolves to an empty (host-less) URL.
+ */
+export declare const DEFAULT_API_BASE = "https://api.qafka.com";
 export declare const STORAGE_KEYS: {
     readonly CONFIG: "@qafka/config";
     readonly CONVERSATION_HISTORY: "@qafka/conversation_history";

package/dist/constants.js

@@ -3,9 +3,19 @@
  * Shared constants for SDK
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STORAGE_KEYS = exports.DEFAULT_API_TIMEOUT = exports.API_VERSION = void 0;
+exports.STORAGE_KEYS = exports.DEFAULT_API_BASE = exports.DEFAULT_API_TIMEOUT = exports.API_VERSION = void 0;
 exports.API_VERSION = 'v1';
 exports.DEFAULT_API_TIMEOUT = 30000;
+/**
+ * Default Qafka backend base host (scheme + host only).
+ *
+ * The REST client appends `/api/v1` and the realtime voice client appends
+ * `/v1/realtime`, so this holds the bare base. Used as the fallback when neither
+ * an explicit `apiUrl` prop nor a runtime-config `apiUrl` is provided — keeps the
+ * REST and voice transports pointed at the same host instead of one silently
+ * defaulting while the other resolves to an empty (host-less) URL.
+ */
+exports.DEFAULT_API_BASE = 'https://api.qafka.com';
 exports.STORAGE_KEYS = {
     CONFIG: '@qafka/config',
     CONVERSATION_HISTORY: '@qafka/conversation_history',

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-/// <reference path="../qafka.config.d.ts" />
 /**
  * QafkaSDK for React Native
  * AI-powered conversational interface with navigation intelligence

package/dist/services/BackendService.d.ts

@@ -1,4 +1,4 @@
-import { ChatResponse } from '../types';
+import { ChatResponse, GenerateImageParams, GenerateImageResult } from '../types';
 /**
  * Backend API Service using native fetch
  */
@@ -19,6 +19,7 @@ export declare class BackendService {
     private onToolDataRequested;
     private readonly toolDataResolvedFor;
     private static readonly RESOLVER_TIMEOUT_MS;
+    private static readonly IMAGE_TIMEOUT_MS;
     constructor(apiKey: string | null, apiUrl?: string, subProjectId?: string);
     setSessionTokenGetter(getter: () => Promise<string | null>): void;
     /**
@@ -80,7 +81,9 @@ export declare class BackendService {
      */
     private postToolData;
     /**
-    * Make HTTP request with timeout
+    * Make HTTP request with timeout. `timeoutMs` optionally overrides the
+    * instance default (`this.timeout`) for calls that are known to run long,
+    * e.g. image generation.
     */
     private fetchWithTimeout;
     /**
@@ -104,6 +107,22 @@ export declare class BackendService {
     */
     getTheme(): Promise<any>;
     /**
+    * Generate one or more images via the backend `/images` endpoint.
+    * Uses a much longer timeout than the default (image inference is slow).
+    * When `params.n` is absent or <= 1, the single result is unwrapped from
+    * the `images` array; otherwise the full array is returned.
+    */
+    generateImage(params: GenerateImageParams): Promise<GenerateImageResult>;
+    /**
+    * Response handler for `/images`. Mirrors `handleResponse`'s ok/!ok split
+    * but maps the server's `errorData.error` onto `Error.code` (same
+    * augmentation pattern as the `DEV_KEY_INVALID` error in
+    * `sendMessageStream`) so callers can branch on stable error codes
+    * (`not_entitled`, `rate_limited`, `content_filtered`, `invalid_reference`,
+    * `generation_failed`, ...) instead of parsing message strings.
+    */
+    private handleImageResponse;
+    /**
     * Send message with streaming response
     * React Native compatible version using XMLHttpRequest
     */

package/dist/services/BackendService.js

@@ -32,6 +32,9 @@ class BackendService {
     onToolDataRequested = null;
     toolDataResolvedFor = new Map();
     static RESOLVER_TIMEOUT_MS = 3000;
+    // Image generation is slow (model inference); give it a much longer
+    // budget than the default 60s used for chat.
+    static IMAGE_TIMEOUT_MS = 120_000;
     constructor(apiKey, apiUrl, subProjectId) {
         // If custom apiUrl provided, ensure it has /api/v1 prefix
         if (apiUrl) {
@@ -233,11 +236,13 @@ class BackendService {
         });
     }
     /**
-    * Make HTTP request with timeout
+    * Make HTTP request with timeout. `timeoutMs` optionally overrides the
+    * instance default (`this.timeout`) for calls that are known to run long,
+    * e.g. image generation.
     */
-    async fetchWithTimeout(url, options) {
+    async fetchWithTimeout(url, options, timeoutMs = this.timeout) {
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const response = await this.fetchWithRefresh(url, {
                 ...options,
@@ -410,6 +415,45 @@ class BackendService {
         }
     }
     /**
+    * Generate one or more images via the backend `/images` endpoint.
+    * Uses a much longer timeout than the default (image inference is slow).
+    * When `params.n` is absent or <= 1, the single result is unwrapped from
+    * the `images` array; otherwise the full array is returned.
+    */
+    async generateImage(params) {
+        const response = await this.fetchWithTimeout(`${this.baseURL}/images`, {
+            method: 'POST',
+            body: JSON.stringify(params),
+        }, BackendService.IMAGE_TIMEOUT_MS);
+        const data = await this.handleImageResponse(response);
+        const images = data.images ?? [];
+        return (params.n ?? 1) > 1 ? images : images[0];
+    }
+    /**
+    * Response handler for `/images`. Mirrors `handleResponse`'s ok/!ok split
+    * but maps the server's `errorData.error` onto `Error.code` (same
+    * augmentation pattern as the `DEV_KEY_INVALID` error in
+    * `sendMessageStream`) so callers can branch on stable error codes
+    * (`not_entitled`, `rate_limited`, `content_filtered`, `invalid_reference`,
+    * `generation_failed`, ...) instead of parsing message strings.
+    */
+    async handleImageResponse(response) {
+        if (response.ok) {
+            return response.json();
+        }
+        const errorData = await response.json().catch(() => ({}));
+        const err = new Error(errorData.message || `❌ Image generation failed (HTTP ${response.status})`);
+        err.code = errorData.error;
+        err.status = response.status;
+        // RateLimitGuard returns 429 with body { error: 'RATE_LIMIT_EXCEEDED' },
+        // but the public contract promises 'rate_limited' — normalize so callers
+        // can reliably branch on it.
+        if (response.status === 429) {
+            err.code = 'rate_limited';
+        }
+        throw err;
+    }
+    /**
     * Send message with streaming response
     * React Native compatible version using XMLHttpRequest
     */

package/dist/types/image.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Image generation types for QafkaSDK
+ * Parameters and results for generateImage() method
+ */
+export interface GenerateImageParams {
+    description: string;
+    referenceImage?: string | string[];
+    aspectRatio?: string;
+    size?: {
+        width: number;
+        height: number;
+    };
+    quality?: 'standard' | 'pro';
+    responseType?: 'base64' | 'url' | 'both';
+    n?: number;
+}
+export interface GeneratedImage {
+    base64?: string;
+    url?: string;
+    expiresAt?: string;
+    mimeType: string;
+}
+export type GenerateImageResult = GeneratedImage | GeneratedImage[];

package/dist/types/image.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Image generation types for QafkaSDK
+ * Parameters and results for generateImage() method
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/index.d.ts

@@ -7,3 +7,4 @@ export * from './chat';
 export * from './sdk';
 export * from './components';
 export * from './external-navigation';
+export * from './image';

package/dist/types/index.js

@@ -23,3 +23,4 @@ __exportStar(require("./chat"), exports);
 __exportStar(require("./sdk"), exports);
 __exportStar(require("./components"), exports);
 __exportStar(require("./external-navigation"), exports);
+__exportStar(require("./image"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qafka/react-native",
-  "version": "2.4.1",
+  "version": "2.5.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",
@@ -23,7 +23,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc && node -e \"const fs=require('fs'),p='dist/index.d.ts',c=fs.readFileSync(p,'utf-8');if(!c.startsWith('/// <reference'))fs.writeFileSync(p,'/// <reference path=\\\"../qafka.config.d.ts\\\" />\\n'+c,'utf-8');\"",
+    "build": "tsc",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",