@qafka/react-native 2.4.2 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,12 @@ 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

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

@@ -383,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/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.2",
+  "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",