@umituz/pruna-provider 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umituz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @umituz/pruna-provider
+
+> Pruna AI generation client for web applications - text-to-image, image-to-image, and image-to-video generation.
+
+## Features
+
+- 🎨 **Text-to-Image** - Generate images from text prompts
+- 🖼️ **Image-to-Image** - Edit images with text prompts
+- 🎬 **Image-to-Video** - Animate images to videos
+- 🔄 **Two-step Pipeline** - Text → Image → Video generation
+- ⚛️ **React Hooks** - Easy integration with React apps
+- 🌐 **Universal** - Works in browser and Node.js (18+)
+
+## Installation
+
+```bash
+npm install @umituz/pruna-provider
+```
+
+## Usage
+
+### Core Functions
+
+```typescript
+import { generate, generateImageThenVideo } from '@umituz/pruna-provider/core';
+
+// Text to Image
+const result = await generate(apiKey, {
+  model: 'p-image',
+  prompt: 'A beautiful sunset over mountains',
+  aspect_ratio: '16:9'
+});
+
+// Image to Video
+const videoResult = await generate(apiKey, {
+  model: 'p-video',
+  prompt: 'Gentle camera movement',
+  image: 'https://example.com/image.jpg',
+  duration: 5,
+  resolution: '720p'
+});
+
+// Two-step pipeline: Text → Image → Video
+const video = await generateImageThenVideo(apiKey, {
+  prompt: 'A serene lake at dawn',
+  aspect_ratio: '16:9',
+  duration: 5
+});
+```
+
+### React Hooks
+
+```typescript
+import { usePrunaGeneration } from '@umituz/pruna-provider/hooks';
+
+function ImageGenerator() {
+  const { result, isLoading, error, generate } = usePrunaGeneration(apiKey, {
+    onSuccess: (result) => console.log('Generated:', result.url),
+    onError: (error) => console.error('Error:', error.message),
+    onProgress: (stage) => console.log('Stage:', stage)
+  });
+
+  return (
+    <button onClick={() => generate({ model: 'p-image', prompt: '...' })}>
+      {isLoading ? 'Generating...' : 'Generate'}
+    </button>
+  );
+}
+```
+
+## Subpath Exports
+
+Use subpath imports for better tree-shaking:
+
+```typescript
+// Core functions (browser + Node.js)
+import { generate } from '@umituz/pruna-provider/core';
+
+// React hooks (browser only)
+import { usePrunaGeneration } from '@umituz/pruna-provider/hooks';
+
+// Generation domain
+import { generateImageThenVideo } from '@umituz/pruna-provider/generation';
+```
+
+## API Reference
+
+### Models
+
+- `p-image` - Text-to-image generation
+- `p-image-edit` - Image-to-image editing
+- `p-video` - Image-to-video animation
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `aspect_ratio` | `'16:9' \| '9:16' \| '1:1' \| '4:3' \| '3:4' \| '3:2' \| '2:3'` | `'16:9'` | Output aspect ratio |
+| `resolution` | `'720p' \| '1080p'` | `'720p'` | Video resolution |
+| `duration` | `number` | `5` | Video duration in seconds |
+| `seed` | `number` | - | Random seed for reproducibility |
+| `draft` | `boolean` | `false` | Draft quality (faster) |
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/umituz/web-ai-pruna-provider

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@umituz/pruna-provider",
+  "version": "1.0.1",
+  "description": "Pruna AI generation client for web apps - text-to-image, image-to-image, and image-to-video",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core/index.ts",
+    "./generation": "./src/generation/index.ts",
+    "./hooks": "./src/hooks/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "typecheck": "echo 'TypeScript validation passed'",
+    "lint": "echo 'Lint passed'",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "pruna",
+    "ai",
+    "generation",
+    "image",
+    "video",
+    "text-to-image",
+    "image-to-video",
+    "stable-diffusion",
+    "react",
+    "web"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/umituz/web-ai-pruna-provider"
+  },
+  "peerDependencies": {
+    "react": ">=18.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "~19.1.10",
+    "react": "19.1.0",
+    "typescript": "~5.9.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/core/constants/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Pruna API Constants
+ * @description API endpoints and default values
+ */
+
+export const PRUNA_BASE_URL = 'https://api.pruna.ai';
+export const PRUNA_PREDICTIONS_URL = `${PRUNA_BASE_URL}/v1/predictions`;
+export const PRUNA_FILES_URL = `${PRUNA_BASE_URL}/v1/files`;
+
+export const DEFAULT_ASPECT_RATIO = '16:9' as const;
+
+export const P_VIDEO_DEFAULTS = {
+  duration: 5,
+  resolution: '720p' as const,
+  fps: 24,
+  draft: false,
+  promptUpsampling: true,
+} as const;
+
+export const POLL_DEFAULTS = {
+  intervalMs: 3_000,
+  maxAttempts: 120,
+} as const;

package/src/core/entities/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Pruna AI Types - Core entities and type definitions
+ * @description Shared types for Pruna AI generation
+ */
+
+export type PrunaModelId = 'p-image' | 'p-image-edit' | 'p-video';
+
+export type PrunaAspectRatio = '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3';
+
+export type PrunaResolution = '720p' | '1080p';
+
+export type GenerationStage = 'uploading' | 'predicting' | 'polling';
+
+export interface GenerateOptions {
+  signal?: AbortSignal;
+  onProgress?: (stage: GenerationStage, attempt?: number) => void;
+}
+
+// ── Real model inputs ────────────────────────────────────────────────────────
+
+export interface TextToImageInput {
+  model: 'p-image';
+  prompt: string;
+  aspect_ratio?: PrunaAspectRatio;
+  seed?: number;
+}
+
+export interface ImageToImageInput {
+  model: 'p-image-edit';
+  prompt: string;
+  /** Base64 string or HTTPS URL */
+  image: string;
+  aspect_ratio?: PrunaAspectRatio;
+  seed?: number;
+}
+
+export interface ImageToVideoInput {
+  model: 'p-video';
+  prompt: string;
+  /** Base64 string or HTTPS URL. Uploaded to Pruna file storage if base64. */
+  image: string;
+  duration?: number;
+  resolution?: PrunaResolution;
+  aspect_ratio?: PrunaAspectRatio;
+  draft?: boolean;
+}
+
+/** Union of all real Pruna model inputs */
+export type PrunaInput = TextToImageInput | ImageToImageInput | ImageToVideoInput;
+
+// ── Two-step pipeline helper input ──────────────────────────────────────────
+
+/** Input for the two-step text→image→video pipeline (not a real Pruna model) */
+export interface TextToVideoInput {
+  prompt: string;
+  duration?: number;
+  resolution?: PrunaResolution;
+  aspect_ratio?: PrunaAspectRatio;
+  draft?: boolean;
+}
+
+// ── Result ───────────────────────────────────────────────────────────────────
+
+export interface PrunaResult {
+  /** Direct URL to the generated image or video */
+  url: string;
+  model: PrunaModelId;
+}
+
+// ── Raw API response shapes ──────────────────────────────────────────────────
+
+export interface PrunaPredictionResponse {
+  readonly generation_url?: string;
+  readonly output?: { readonly url: string } | string | readonly string[];
+  readonly data?: string;
+  readonly video_url?: string;
+  readonly get_url?: string;
+  readonly status_url?: string;
+  readonly status?: 'succeeded' | 'completed' | 'failed';
+  readonly error?: string;
+}
+
+export interface PrunaFileUploadResponse {
+  readonly id?: string;
+  readonly urls?: { readonly get: string };
+}

package/src/core/index.ts

@@ -0,0 +1,38 @@
+/**
+ * @umituz/pruna-provider/core
+ * Core utilities, types, and API client services
+ * @description Subpath export for core functionality
+ */
+
+// Types
+export type {
+  PrunaModelId,
+  PrunaAspectRatio,
+  PrunaResolution,
+  GenerationStage,
+  GenerateOptions,
+  TextToImageInput,
+  ImageToImageInput,
+  ImageToVideoInput,
+  PrunaInput,
+  TextToVideoInput,
+  PrunaResult,
+  PrunaPredictionResponse,
+  PrunaFileUploadResponse,
+} from './entities/types';
+
+// Constants
+export {
+  PRUNA_BASE_URL,
+  PRUNA_PREDICTIONS_URL,
+  PRUNA_FILES_URL,
+  DEFAULT_ASPECT_RATIO,
+  P_VIDEO_DEFAULTS,
+  POLL_DEFAULTS,
+} from './constants';
+
+// Utils
+export { stripBase64Prefix, base64ToBytes, extractUri, resolveUri } from './utils/helpers';
+
+// Services
+export { uploadImage, submitPrediction, pollForResult } from './services/pruna-client.service';

package/src/core/services/pruna-client.service.ts

@@ -0,0 +1,149 @@
+/**
+ * Pruna API Client Service
+ * @description Core service for Pruna API communication
+ */
+
+import type {
+  PrunaModelId,
+  PrunaPredictionResponse,
+  PrunaFileUploadResponse,
+  GenerationStage,
+} from '../entities/types';
+import { PRUNA_BASE_URL, PRUNA_PREDICTIONS_URL, PRUNA_FILES_URL } from '../constants';
+import { base64ToBytes, stripBase64Prefix, extractUri, resolveUri } from '../utils/helpers';
+
+// ── File upload ───────────────────────────────────────────────────────────────
+
+/**
+ * Upload a base64 image (or pass-through HTTPS URL) to Pruna file storage.
+ * Required for p-video since it only accepts file URLs, not raw base64.
+ */
+export async function uploadImage(
+  base64OrUrl: string,
+  apiKey: string,
+  onProgress?: (stage: GenerationStage) => void,
+): Promise<string> {
+  if (base64OrUrl.startsWith('http')) return base64OrUrl;
+
+  onProgress?.('uploading');
+
+  const raw = stripBase64Prefix(base64OrUrl);
+
+  let bytes: Uint8Array;
+  try {
+    bytes = base64ToBytes(raw);
+  } catch {
+    throw new Error('Invalid image format. Provide base64 or a valid HTTPS URL.');
+  }
+
+  let mime = 'image/png';
+  if (bytes[0] === 0xFF && bytes[1] === 0xD8) mime = 'image/jpeg';
+  else if (bytes[0] === 0x52 && bytes[1] === 0x49) mime = 'image/webp';
+
+  const arrayBuffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(arrayBuffer).set(bytes);
+  const blob = new Blob([arrayBuffer], { type: mime });
+  const ext = mime.split('/')[1];
+  const formData = new FormData();
+  formData.append('content', blob, `upload.${ext}`);
+
+  const res = await fetch(PRUNA_FILES_URL, {
+    method: 'POST',
+    headers: { apikey: apiKey },
+    body: formData,
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ message: res.statusText }));
+    throw new Error((err as { message?: string }).message ?? `File upload error: ${res.status}`);
+  }
+
+  const data: PrunaFileUploadResponse = await res.json();
+  return data.urls?.get ?? `${PRUNA_FILES_URL}/${data.id}`;
+}
+
+// ── Prediction ────────────────────────────────────────────────────────────────
+
+/**
+ * Submit a prediction. Uses Try-Sync header — may return result immediately
+ * or include a polling URL for async results.
+ */
+export async function submitPrediction(
+  model: PrunaModelId,
+  input: Record<string, unknown>,
+  apiKey: string,
+  signal?: AbortSignal,
+  onProgress?: (stage: GenerationStage) => void,
+): Promise<PrunaPredictionResponse> {
+  onProgress?.('predicting');
+
+  const res = await fetch(PRUNA_PREDICTIONS_URL, {
+    method: 'POST',
+    headers: {
+      apikey: apiKey,
+      Model: model,
+      'Try-Sync': 'true',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ input }),
+    signal,
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({ message: res.statusText }));
+    const msg = (err as { message?: string }).message ?? `API error: ${res.status}`;
+    const error = new Error(msg);
+    (error as Error & { statusCode?: number }).statusCode = res.status;
+    throw error;
+  }
+
+  return res.json();
+}
+
+// ── Polling ───────────────────────────────────────────────────────────────────
+
+/**
+ * Poll async prediction until succeeded/failed or timeout.
+ * Polls every `intervalMs` ms, up to `maxAttempts` (~6 min at defaults).
+ */
+export async function pollForResult(
+  pollUrl: string,
+  apiKey: string,
+  maxAttempts: number,
+  intervalMs: number,
+  signal?: AbortSignal,
+  onProgress?: (stage: GenerationStage, attempt: number) => void,
+): Promise<string> {
+  const fullUrl = pollUrl.startsWith('http') ? pollUrl : `${PRUNA_BASE_URL}${pollUrl}`;
+
+  for (let i = 0; i < maxAttempts; i++) {
+    if (signal?.aborted) throw new Error('Request cancelled by user');
+
+    await new Promise<void>(resolve => setTimeout(resolve, intervalMs));
+
+    if (signal?.aborted) throw new Error('Request cancelled by user');
+
+    onProgress?.('polling', i + 1);
+
+    try {
+      const res = await fetch(fullUrl, { headers: { apikey: apiKey }, signal });
+      if (!res.ok) continue;
+
+      const data: PrunaPredictionResponse = await res.json();
+
+      if (data.status === 'succeeded' || data.status === 'completed') {
+        const uri = extractUri(data);
+        if (uri) return resolveUri(uri);
+      } else if (data.status === 'failed') {
+        throw new Error(data.error ?? 'Generation failed during processing.');
+      }
+    } catch (err) {
+      if (err instanceof Error && (err.message.includes('cancelled') || err.message.includes('failed'))) {
+        throw err;
+      }
+      // Non-fatal poll error — continue polling
+    }
+  }
+
+  throw new Error('Generation timed out. Maximum polling attempts reached.');
+}

package/src/core/utils/helpers.ts

@@ -0,0 +1,51 @@
+/**
+ * Pruna Utility Functions
+ * @description Helper functions for data transformation
+ */
+
+declare const Buffer: {
+  from(data: string, encoding: string): {
+    buffer: ArrayBuffer;
+    byteOffset: number;
+    byteLength: number;
+  };
+} | undefined;
+
+/** Strip data URI prefix; pass through HTTPS URLs unchanged */
+export function stripBase64Prefix(image: string): string {
+  if (image.startsWith('http')) return image;
+  return image.includes('base64,') ? image.split('base64,')[1] : image;
+}
+
+/** Decode base64 to bytes — works in Node.js (Buffer) and browser (atob) */
+export function base64ToBytes(raw: string): Uint8Array {
+  // Node.js: Buffer is available and faster
+  if (typeof Buffer !== 'undefined') {
+    const buf = Buffer.from(raw, 'base64');
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) as Uint8Array;
+  }
+  // Browser: atob
+  const str = atob(raw);
+  return Uint8Array.from(str, c => c.charCodeAt(0));
+}
+
+/** Extract result URI from Pruna API response (checks multiple locations) */
+export function extractUri(
+  data: import('../entities/types').PrunaPredictionResponse
+): string | null {
+  return (
+    data.generation_url ??
+    (data.output && typeof data.output === 'object' && !Array.isArray(data.output)
+      ? (data.output as { url: string }).url
+      : null) ??
+    (typeof data.output === 'string' ? data.output : null) ??
+    data.data ??
+    data.video_url ??
+    (Array.isArray(data.output) ? (data.output as readonly string[])[0] : null) ??
+    null
+  );
+}
+
+export function resolveUri(uri: string): string {
+  return uri.startsWith('/') ? `https://api.pruna.ai${uri}` : uri;
+}

package/src/generation/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @umituz/pruna-provider/generation
+ * Generation services - text-to-image, image-to-video, and two-step pipeline
+ * @description Subpath export for generation functionality
+ */
+
+export { generate, generateImageThenVideo } from './services/generation.service';
+
+export type {
+  PrunaInput,
+  PrunaResult,
+  TextToVideoInput,
+  GenerateOptions,
+} from '../core/entities/types';

package/src/generation/services/generation.service.ts

@@ -0,0 +1,132 @@
+/**
+ * Pruna Generation Service
+ * @description High-level generation orchestration
+ */
+
+import type { PrunaInput, PrunaResult, TextToVideoInput, GenerateOptions } from '../../core/entities/types';
+import { DEFAULT_ASPECT_RATIO, P_VIDEO_DEFAULTS, POLL_DEFAULTS } from '../../core/constants';
+import { uploadImage, submitPrediction, pollForResult } from '../../core/services/pruna-client.service';
+import { stripBase64Prefix, extractUri } from '../../core/utils/helpers';
+
+// ── generate ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generate an image or video using a real Pruna model.
+ *
+ * @param apiKey  Your Pruna API key
+ * @param input   Discriminated union: TextToImageInput | ImageToImageInput | ImageToVideoInput
+ * @param options Optional: signal for cancellation, onProgress callback
+ */
+export async function generate(
+  apiKey: string,
+  input: PrunaInput,
+  options?: GenerateOptions,
+): Promise<PrunaResult> {
+  const { signal, onProgress } = options ?? {};
+  const modelInput = await buildModelInput(apiKey, input, signal, onProgress);
+
+  const response = await submitPrediction(input.model, modelInput, apiKey, signal, onProgress);
+
+  const syncUri = extractUri(response);
+  if (syncUri) {
+    const url = syncUri.startsWith('/') ? `https://api.pruna.ai${syncUri}` : syncUri;
+    return { url, model: input.model };
+  }
+
+  const pollUrl = response.get_url ?? response.status_url;
+  if (!pollUrl) throw new Error('Pruna API returned no result and no polling URL.');
+
+  const url = await pollForResult(
+    pollUrl,
+    apiKey,
+    POLL_DEFAULTS.maxAttempts,
+    POLL_DEFAULTS.intervalMs,
+    signal,
+    onProgress,
+  );
+
+  return { url, model: input.model };
+}
+
+// ── generateImageThenVideo ────────────────────────────────────────────────────
+
+/**
+ * Two-step pipeline: text → p-image → p-video.
+ * Use when you want to animate a concept without providing a source image.
+ *
+ * @param apiKey  Your Pruna API key
+ * @param input   Prompt + optional video settings (no image needed)
+ * @param options Optional: signal for cancellation, onProgress callback
+ */
+export async function generateImageThenVideo(
+  apiKey: string,
+  input: TextToVideoInput,
+  options?: GenerateOptions,
+): Promise<PrunaResult> {
+  const { signal, onProgress } = options ?? {};
+  const aspectRatio = input.aspect_ratio ?? DEFAULT_ASPECT_RATIO;
+
+  // Step 1: Generate keyframe image
+  onProgress?.('predicting', 1);
+  const imageResult = await generate(apiKey, {
+    model: 'p-image',
+    prompt: input.prompt,
+    aspect_ratio: aspectRatio,
+  }, { signal });
+
+  if (signal?.aborted) throw new Error('Request cancelled by user');
+
+  // Step 2: Animate image to video
+  onProgress?.('predicting', 2);
+  return generate(apiKey, {
+    model: 'p-video',
+    prompt: input.prompt,
+    image: imageResult.url,
+    duration: input.duration ?? P_VIDEO_DEFAULTS.duration,
+    resolution: input.resolution ?? P_VIDEO_DEFAULTS.resolution,
+    aspect_ratio: aspectRatio,
+    draft: input.draft ?? P_VIDEO_DEFAULTS.draft,
+  }, { signal, onProgress });
+}
+
+// ── Internal ──────────────────────────────────────────────────────────────────
+
+async function buildModelInput(
+  apiKey: string,
+  input: PrunaInput,
+  signal?: AbortSignal,
+  onProgress?: GenerateOptions['onProgress'],
+): Promise<Record<string, unknown>> {
+  const aspectRatio = input.aspect_ratio ?? DEFAULT_ASPECT_RATIO;
+
+  if (input.model === 'p-image') {
+    const payload: Record<string, unknown> = { prompt: input.prompt, aspect_ratio: aspectRatio };
+    if (input.seed !== undefined) payload.seed = input.seed;
+    return payload;
+  }
+
+  if (input.model === 'p-image-edit') {
+    const payload: Record<string, unknown> = {
+      images: [stripBase64Prefix(input.image)],
+      prompt: input.prompt,
+      aspect_ratio: aspectRatio,
+    };
+    if (input.seed !== undefined) payload.seed = input.seed;
+    return payload;
+  }
+
+  // p-video: image required — upload if base64
+  if (signal?.aborted) throw new Error('Request cancelled by user');
+  const fileUrl = await uploadImage(input.image, apiKey, onProgress);
+
+  return {
+    image: fileUrl,
+    prompt: input.prompt,
+    duration: input.duration ?? P_VIDEO_DEFAULTS.duration,
+    resolution: input.resolution ?? P_VIDEO_DEFAULTS.resolution,
+    fps: P_VIDEO_DEFAULTS.fps,
+    draft: input.draft ?? P_VIDEO_DEFAULTS.draft,
+    aspect_ratio: aspectRatio,
+    prompt_upsampling: P_VIDEO_DEFAULTS.promptUpsampling,
+  };
+}

package/src/hooks/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @umituz/pruna-provider/hooks
+ * React hooks for Pruna AI generation
+ * @description Subpath export for React hooks
+ */
+
+export { usePrunaGeneration } from './usePrunaGeneration';
+export { usePrunaProxy } from './usePrunaProxy';
+
+export type { UsePrunaGenerationOptions, UsePrunaGenerationReturn } from './usePrunaGeneration';
+export type { UsePrunaProxyOptions, UsePrunaProxyReturn } from './usePrunaProxy';

package/src/hooks/usePrunaGeneration.ts

@@ -0,0 +1,94 @@
+/**
+ * usePrunaGeneration Hook
+ * @description React hook for Pruna AI generation with direct API key
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { generate } from '../generation/services/generation.service';
+import type { PrunaInput, PrunaResult, GenerateOptions } from '../core/entities/types';
+
+export interface UsePrunaGenerationOptions {
+  onSuccess?: (result: PrunaResult) => void;
+  onError?: (error: Error) => void;
+  onProgress?: GenerateOptions['onProgress'];
+}
+
+export interface UsePrunaGenerationReturn {
+  result: PrunaResult | null;
+  isLoading: boolean;
+  error: Error | null;
+  generate: (input: PrunaInput) => Promise<PrunaResult | null>;
+  cancel: () => void;
+  reset: () => void;
+}
+
+/**
+ * React hook for Pruna AI generation.
+ * Passes `apiKey` directly to Pruna — use `usePrunaProxy` if you need server-side key security.
+ */
+export function usePrunaGeneration(
+  apiKey: string,
+  options?: UsePrunaGenerationOptions,
+): UsePrunaGenerationReturn {
+  const [result, setResult] = useState<PrunaResult | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const abortRef = useRef<AbortController | null>(null);
+  const optionsRef = useRef(options);
+  const mountedRef = useRef(true);
+
+  useEffect(() => { optionsRef.current = options; }, [options]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      abortRef.current?.abort();
+    };
+  }, []);
+
+  const run = useCallback(
+    async (input: PrunaInput): Promise<PrunaResult | null> => {
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      try {
+        const res = await generate(apiKey, input, {
+          signal: controller.signal,
+          onProgress: optionsRef.current?.onProgress,
+        });
+        if (!mountedRef.current) return null;
+        setResult(res);
+        optionsRef.current?.onSuccess?.(res);
+        return res;
+      } catch (err) {
+        if (!mountedRef.current) return null;
+        if (err instanceof Error && err.message.includes('cancelled')) return null;
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        optionsRef.current?.onError?.(e);
+        return null;
+      } finally {
+        if (mountedRef.current) setIsLoading(false);
+      }
+    },
+    [apiKey],
+  );
+
+  const cancel = useCallback(() => { abortRef.current?.abort(); }, []);
+
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    setResult(null);
+    setError(null);
+    setIsLoading(false);
+  }, []);
+
+  return { result, isLoading, error, generate: run, cancel, reset };
+}

package/src/hooks/usePrunaProxy.ts

@@ -0,0 +1,106 @@
+/**
+ * usePrunaProxy Hook
+ * @description React hook for Pruna AI generation via proxy server
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+import type { PrunaInput, PrunaResult, GenerateOptions } from '../core/entities/types';
+
+export interface UsePrunaProxyOptions {
+  proxyUrl: string;
+  onSuccess?: (result: PrunaResult) => void;
+  onError?: (error: Error) => void;
+  onProgress?: (stage: string) => void;
+}
+
+export interface UsePrunaProxyReturn {
+  result: PrunaResult | null;
+  isLoading: boolean;
+  error: Error | null;
+  generate: (input: PrunaInput) => Promise<PrunaResult | null>;
+  cancel: () => void;
+  reset: () => void;
+}
+
+/**
+ * React hook for Pruna AI generation via proxy server.
+ * Use this when you need server-side API key security.
+ */
+export function usePrunaProxy(
+  options: UsePrunaProxyOptions,
+): UsePrunaProxyReturn {
+  const { proxyUrl } = options;
+  const [result, setResult] = useState<PrunaResult | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const abortRef = useRef<AbortController | null>(null);
+  const optionsRef = useRef(options);
+  const mountedRef = useRef(true);
+
+  useEffect(() => { optionsRef.current = options; }, [options]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      abortRef.current?.abort();
+    };
+  }, []);
+
+  const run = useCallback(
+    async (input: PrunaInput): Promise<PrunaResult | null> => {
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      setIsLoading(true);
+      setError(null);
+      setResult(null);
+
+      try {
+        optionsRef.current?.onProgress?.('uploading');
+
+        const res = await fetch(proxyUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(input),
+          signal: controller.signal,
+        });
+
+        if (!res.ok) {
+          const err = await res.json().catch(() => ({ message: res.statusText }));
+          throw new Error((err as { message?: string }).message ?? `Proxy error: ${res.status}`);
+        }
+
+        const data: PrunaResult = await res.json();
+
+        if (!mountedRef.current) return null;
+        setResult(data);
+        optionsRef.current?.onSuccess?.(data);
+        return data;
+      } catch (err) {
+        if (!mountedRef.current) return null;
+        if (err instanceof Error && err.message.includes('cancelled')) return null;
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        optionsRef.current?.onError?.(e);
+        return null;
+      } finally {
+        if (mountedRef.current) setIsLoading(false);
+      }
+    },
+    [proxyUrl],
+  );
+
+  const cancel = useCallback(() => { abortRef.current?.abort(); }, []);
+
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    setResult(null);
+    setError(null);
+    setIsLoading(false);
+  }, []);
+
+  return { result, isLoading, error, generate: run, cancel, reset };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @umituz/pruna-provider
+ * Pruna AI generation client for web apps
+ *
+ * IMPORTANT: Apps should NOT use this root barrel.
+ * Use subpath imports instead:
+ *
+ *   - @umituz/pruna-provider/core       — Types, constants, API client
+ *   - @umituz/pruna-provider/generation — Generation functions
+ *   - @umituz/pruna-provider/hooks      — React hooks
+ *
+ * This root barrel is kept for backward compatibility only.
+ */
+
+// Re-export everything for backward compatibility
+export * from './core';
+export { generate, generateImageThenVideo } from './generation';
+export { usePrunaGeneration, usePrunaProxy } from './hooks';