@enfyra/sdk-nuxt 0.2.1 → 0.2.3

package/README.md

@@ -7,7 +7,7 @@ Nuxt SDK for Enfyra CMS - A powerful composable-based API client with full SSR s
 ✅ **SSR & Client-Side Support** - Automatic server-side rendering with `useFetch` or client-side with `$fetch`  
 ✅ **Authentication Integration** - Built-in auth composables with automatic header forwarding  
 ✅ **TypeScript Support** - Full type safety with auto-generated declarations  
-✅ **Batch Operations** - Efficient bulk operations for CRUD actions (client-side)  
+✅ **Batch Operations** - Efficient bulk operations with real-time progress tracking (client-side)  
 ✅ **Error Handling** - Automatic error management with console logging  
 ✅ **Reactive State** - Built-in loading, error, and data states  
 ✅ **Caching Support** - Optional cache keys for SSR mode optimization  
@@ -143,19 +143,36 @@ await execute({
 - `query?: Record<string, any>` - URL query parameters
 - `headers?: Record<string, string>` - Custom headers
 - `errorContext?: string` - Error context for logging
+- `onError?: (error: ApiError, context?: string) => void` - Custom error handler
 - `key?: string` - Cache key (SSR mode, optional)
 - `default?: () => T` - Default value (SSR mode only)
 
+**Batch Options (only available for PATCH, DELETE, and POST methods):**
+- `batchSize?: number` - Batch size for chunking large operations (default: no limit)
+- `concurrent?: number` - Maximum concurrent requests (default: no limit)
+- `onProgress?: (progress: BatchProgress) => void` - Real-time progress callback for batch operations
+
+> 🎯 **TypeScript Smart:** Batch options (`batchSize`, `concurrent`, `onProgress`) are only available in TypeScript IntelliSense when using methods that support batch operations (PATCH, DELETE, POST). For GET and PUT methods, these options won't appear in autocomplete.
+
 **⚠️ Important: Return Types Differ**
 - **SSR Mode**: Returns `useFetch` result `{ data, pending, error, refresh }`
 - **Client Mode**: Returns custom result `{ data, pending, error, execute }`
 
 **Execute Options (Client mode only):**
+
+**Basic Options:**
 - `id?: string | number` - Single resource ID
-- `ids?: (string | number)[]` - Batch operation IDs (PATCH/DELETE)
-- `files?: FormData[]` - Batch file upload (POST)
 - `body?: any` - Override request body
 
+**Batch Options (only when using `ids` or `files`):**
+- `ids?: (string | number)[]` - Batch operation IDs (PATCH/DELETE)
+- `files?: FormData[]` - Array of FormData objects for batch upload (POST)
+- `batchSize?: number` - Override batch size for this execution
+- `concurrent?: number` - Override concurrent limit for this execution
+- `onProgress?: (progress: BatchProgress) => void` - Override progress callback for this execution
+
+> 🎯 **TypeScript Smart:** Batch execute options (`batchSize`, `concurrent`, `onProgress`) are only available when you provide `ids` or `files` parameters, ensuring type safety.
+
 ### `useEnfyraAuth()`
 
 Authentication composable with reactive state management.
@@ -178,7 +195,8 @@ await fetchUser()                 // Refresh user data
 ### Batch Operations
 
 ```typescript
-// Batch delete multiple items
+// Basic batch delete - unlimited parallel requests
+// 🎯 Note: Batch options only appear in IntelliSense for DELETE method
 const { execute: deleteItems } = useEnfyraApi('/items', {
   method: 'delete',
   errorContext: 'Delete Items'
@@ -186,15 +204,155 @@ const { execute: deleteItems } = useEnfyraApi('/items', {
 
 await deleteItems({ ids: ['1', '2', '3'] });
 
-// Batch file upload
-const { execute: uploadFiles } = useEnfyraApi('/files', {
-  method: 'post', 
-  errorContext: 'Upload Files'
+// Advanced batch operations with concurrency control  
+// 🎯 TypeScript shows batch options (batchSize, concurrent, onProgress) for DELETE method
+const { execute: deleteMany } = useEnfyraApi('/users', {
+  method: 'delete',
+  batchSize: 10,      // ✅ Available: DELETE method supports batching
+  concurrent: 3,      // ✅ Available: DELETE method supports batching  
+  onProgress: (progress) => {  // ✅ Available: DELETE method supports batching
+    console.log(`Deleting: ${progress.completed}/${progress.total}`);
+  },
+  onError: (error, context) => toast.error(`${context}: ${error.message}`)
+});
+
+// GET method example - batch options NOT available
+// 🎯 TypeScript won't show batch options for GET method
+const { execute: getUsers } = useEnfyraApi('/users', {
+  method: 'get',
+  // batchSize: 10,      // ❌ Not available: GET doesn't support batching
+  // concurrent: 3,      // ❌ Not available: GET doesn't support batching
+  // onProgress: () => {}  // ❌ Not available: GET doesn't support batching
+  errorContext: 'Fetch Users'
+});
+
+// Delete 100 users in controlled batches
+await deleteMany({ ids: Array.from({length: 100}, (_, i) => `user-${i}`) });
+
+// Override batch settings per execution
+// 🎯 TypeScript shows batch options for PATCH method
+const { execute: updateUsers } = useEnfyraApi('/users', {
+  method: 'patch',
+  batchSize: 20,     // ✅ Available: PATCH method supports batching
+  concurrent: 5      // ✅ Available: PATCH method supports batching
+});
+
+// This execution uses different settings
+// 🎯 Batch options in execute() only available when using `ids` or `files`
+await updateUsers({ 
+  ids: largeUserList,           // ✅ Triggers batch mode
+  body: { status: 'active' },
+  batchSize: 50,     // ✅ Available: Using `ids` parameter  
+  concurrent: 10,    // ✅ Available: Using `ids` parameter
+  onProgress: (progress) => {   // ✅ Available: Using `ids` parameter
+    console.log(`Updating: ${progress.completed}/${progress.total}`);
+  }
+});
+
+// Single operation - batch options NOT available in execute
+await updateUsers({
+  id: 'single-user-id',         // ❌ Single operation, no batch options
+  body: { status: 'active' }
+  // batchSize: 50,             // ❌ Not available: Not using `ids` or `files`
+  // concurrent: 10,            // ❌ Not available: Not using `ids` or `files`  
+  // onProgress: () => {}       // ❌ Not available: Not using `ids` or `files`
+});
+
+// Batch file upload with real-time progress tracking
+const progressState = ref({
+  progress: 0,
+  completed: 0,
+  total: 0,
+  failed: 0,
+  estimatedTimeRemaining: 0,
+  operationsPerSecond: 0
+});
+
+// 🎯 TypeScript shows batch options for POST method (supports file uploads)
+const { execute: uploadFiles } = useEnfyraApi('/file_definition', {
+  method: 'post',
+  batchSize: 5,      // ✅ Available: POST method supports batching for files
+  concurrent: 2,     // ✅ Available: POST method supports batching for files
+  errorContext: 'Upload Files',
+  onProgress: (progress) => {  // ✅ Available: POST method supports batching
+    progressState.value = progress;
+    console.log(`Progress: ${progress.progress}% (${progress.completed}/${progress.total})`);
+    console.log(`ETA: ${Math.round((progress.estimatedTimeRemaining || 0) / 1000)}s`);
+    console.log(`Speed: ${progress.operationsPerSecond?.toFixed(1)} ops/sec`);
+  }
+});
+
+// Convert files to FormData array (matches enfyra_app pattern)
+const formDataArray = selectedFiles.map(file => {
+  const formData = new FormData();
+  formData.append('file', file);
+  formData.append('folder', folderId || 'null');
+  return formData;
 });
 
 await uploadFiles({ 
-  files: [formData1, formData2, formData3] 
+  files: formDataArray // Array of FormData objects
 });
+
+// Real-time progress tracking with detailed results
+const { execute: processData } = useEnfyraApi('/process', {
+  method: 'post',
+  batchSize: 10,
+  concurrent: 3,
+  onProgress: (progress) => {
+    // Display progress bar
+    updateProgressBar(progress.progress);
+    
+    // Show detailed metrics
+    console.log('Batch Progress:', {
+      percentage: progress.progress,
+      completed: progress.completed,
+      total: progress.total,
+      failed: progress.failed,
+      currentBatch: progress.currentBatch,
+      totalBatches: progress.totalBatches,
+      averageTime: progress.averageTime,
+      estimatedTimeRemaining: progress.estimatedTimeRemaining,
+      operationsPerSecond: progress.operationsPerSecond
+    });
+    
+    // Handle individual results
+    progress.results.forEach(result => {
+      if (result.status === 'failed') {
+        console.error(`Item ${result.index} failed:`, result.error);
+      }
+    });
+  }
+});
+
+await processData({ 
+  ids: largeDataSet,
+  body: processingOptions 
+});
+```
+
+### Real-time Progress Interface
+
+```typescript
+interface BatchProgress {
+  progress: number;                    // 0-100 percentage
+  completed: number;                   // Number of completed operations
+  total: number;                       // Total number of operations
+  failed: number;                      // Number of failed operations
+  inProgress: number;                  // Operations currently running
+  estimatedTimeRemaining?: number;     // Milliseconds remaining
+  averageTime?: number;                // Average time per operation (ms)
+  currentBatch: number;               // Current batch being processed
+  totalBatches: number;               // Total number of batches
+  operationsPerSecond?: number;       // Processing speed
+  results: Array<{                    // Detailed results
+    index: number;
+    status: 'completed' | 'failed';
+    result?: any;
+    error?: ApiError;
+    duration?: number;
+  }>;
+}
 ```
 
 ### TypeScript Integration
@@ -269,7 +427,7 @@ export default defineNuxtConfig({
     // Required: Main API URL
     apiUrl: process.env.ENFYRA_API_URL || "http://localhost:1105",
     
-    // Optional: API path prefix (default: '')
+    // Optional: API path prefix (default: '/api')
     apiPrefix: '/api/v1',
     
     // Required: App URL for SSR requests  

package/dist/composables/useEnfyraApi.mjs

@@ -16,7 +16,7 @@ function handleError(error, context, customHandler) {
   return apiError;
 }
 export function useEnfyraApi(path, opts = {}) {
-  const { method = "get", body, query, errorContext, onError, ssr, key } = opts;
+  const { method = "get", body, query, errorContext, onError, ssr, key, batchSize, concurrent, onProgress } = opts;
   if (ssr) {
     const config = useRuntimeConfig().public.enfyraSDK;
     const basePath = (typeof path === "function" ? path() : path).replace(/^\/?api\/?/, "").replace(/^\/+/, "");
@@ -65,12 +65,165 @@ export function useEnfyraApi(path, opts = {}) {
       const basePath = (typeof path === "function" ? path() : path).replace(/^\/?api\/?/, "").replace(/^\/+/, "");
       const finalBody = executeOpts?.body || unref(body);
       const finalQuery = unref(query);
+      const isBatchOperation = !opts.disableBatch && (executeOpts?.ids && executeOpts.ids.length > 0 && (method.toLowerCase() === "patch" || method.toLowerCase() === "delete") || method.toLowerCase() === "post" && executeOpts?.files && Array.isArray(executeOpts.files) && executeOpts.files.length > 0);
+      const effectiveBatchSize = isBatchOperation ? executeOpts?.batchSize ?? batchSize : void 0;
+      const effectiveConcurrent = isBatchOperation ? executeOpts?.concurrent ?? concurrent : void 0;
+      const effectiveOnProgress = isBatchOperation ? executeOpts?.onProgress ?? onProgress : void 0;
       const buildPath = (...segments) => {
         return segments.filter(Boolean).join("/");
       };
       const fullBaseURL = apiUrl + (apiPrefix || "");
-      if (!opts.disableBatch && executeOpts?.ids && executeOpts.ids.length > 0 && (method.toLowerCase() === "patch" || method.toLowerCase() === "delete")) {
-        const promises = executeOpts.ids.map(async (id) => {
+      async function processBatch(items, processor) {
+        const results = [];
+        const progressResults = [];
+        const startTime = Date.now();
+        let completed = 0;
+        let failed = 0;
+        const chunks = effectiveBatchSize ? Array.from(
+          { length: Math.ceil(items.length / effectiveBatchSize) },
+          (_, i) => items.slice(i * effectiveBatchSize, i * effectiveBatchSize + effectiveBatchSize)
+        ) : [items];
+        const totalBatches = chunks.length;
+        let currentBatch = 0;
+        const updateProgress = (inProgress = 0) => {
+          if (effectiveOnProgress) {
+            const elapsed = Date.now() - startTime;
+            const progress = items.length > 0 ? Math.round(completed / items.length * 100) : 0;
+            const averageTime = completed > 0 ? elapsed / completed : void 0;
+            const operationsPerSecond = completed > 0 ? completed / elapsed * 1e3 : void 0;
+            const estimatedTimeRemaining = averageTime && items.length > completed ? Math.round(averageTime * (items.length - completed)) : void 0;
+            const progressData = {
+              progress,
+              completed,
+              total: items.length,
+              failed,
+              inProgress,
+              estimatedTimeRemaining,
+              averageTime,
+              currentBatch: currentBatch + 1,
+              totalBatches,
+              operationsPerSecond,
+              results: [...progressResults]
+            };
+            effectiveOnProgress(progressData);
+          }
+        };
+        updateProgress(0);
+        if (!effectiveBatchSize && !effectiveConcurrent) {
+          updateProgress(items.length);
+          const promises = items.map(async (item, index) => {
+            const itemStartTime = Date.now();
+            try {
+              const result = await processor(item, index);
+              const duration = Date.now() - itemStartTime;
+              completed++;
+              progressResults.push({
+                index,
+                status: "completed",
+                result,
+                duration
+              });
+              updateProgress(items.length - completed);
+              return result;
+            } catch (error2) {
+              const duration = Date.now() - itemStartTime;
+              failed++;
+              completed++;
+              progressResults.push({
+                index,
+                status: "failed",
+                error: error2,
+                duration
+              });
+              updateProgress(items.length - completed);
+              throw error2;
+            }
+          });
+          const results2 = await Promise.all(promises);
+          updateProgress(0);
+          return results2;
+        }
+        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+          currentBatch = chunkIndex;
+          const chunk = chunks[chunkIndex];
+          if (effectiveConcurrent && chunk.length > effectiveConcurrent) {
+            for (let i = 0; i < chunk.length; i += effectiveConcurrent) {
+              const batch = chunk.slice(i, i + effectiveConcurrent);
+              const baseIndex = chunkIndex * (effectiveBatchSize || items.length) + i;
+              updateProgress(batch.length);
+              const batchPromises = batch.map(async (item, batchItemIndex) => {
+                const globalIndex = baseIndex + batchItemIndex;
+                const itemStartTime = Date.now();
+                try {
+                  const result = await processor(item, globalIndex);
+                  const duration = Date.now() - itemStartTime;
+                  completed++;
+                  progressResults.push({
+                    index: globalIndex,
+                    status: "completed",
+                    result,
+                    duration
+                  });
+                  updateProgress(Math.max(0, batch.length - (batchItemIndex + 1)));
+                  return result;
+                } catch (error2) {
+                  const duration = Date.now() - itemStartTime;
+                  failed++;
+                  completed++;
+                  progressResults.push({
+                    index: globalIndex,
+                    status: "failed",
+                    error: error2,
+                    duration
+                  });
+                  updateProgress(Math.max(0, batch.length - (batchItemIndex + 1)));
+                  throw error2;
+                }
+              });
+              const batchResults = await Promise.all(batchPromises);
+              results.push(...batchResults);
+            }
+          } else {
+            const baseIndex = chunkIndex * (effectiveBatchSize || items.length);
+            updateProgress(chunk.length);
+            const chunkPromises = chunk.map(async (item, chunkItemIndex) => {
+              const globalIndex = baseIndex + chunkItemIndex;
+              const itemStartTime = Date.now();
+              try {
+                const result = await processor(item, globalIndex);
+                const duration = Date.now() - itemStartTime;
+                completed++;
+                progressResults.push({
+                  index: globalIndex,
+                  status: "completed",
+                  result,
+                  duration
+                });
+                updateProgress(Math.max(0, chunk.length - (chunkItemIndex + 1)));
+                return result;
+              } catch (error2) {
+                const duration = Date.now() - itemStartTime;
+                failed++;
+                completed++;
+                progressResults.push({
+                  index: globalIndex,
+                  status: "failed",
+                  error: error2,
+                  duration
+                });
+                updateProgress(Math.max(0, chunk.length - (chunkItemIndex + 1)));
+                throw error2;
+              }
+            });
+            const chunkResults = await Promise.all(chunkPromises);
+            results.push(...chunkResults);
+          }
+        }
+        updateProgress(0);
+        return results;
+      }
+      if (isBatchOperation && executeOpts?.ids && executeOpts.ids.length > 0) {
+        const responses = await processBatch(executeOpts.ids, async (id, index) => {
           const finalPath2 = buildPath(basePath, id);
           return $fetch(finalPath2, {
             baseURL: fullBaseURL,
@@ -80,12 +233,11 @@ export function useEnfyraApi(path, opts = {}) {
             query: finalQuery
           });
         });
-        const responses = await Promise.all(promises);
         data.value = responses;
         return responses;
       }
-      if (!opts.disableBatch && method.toLowerCase() === "post" && executeOpts?.files && Array.isArray(executeOpts.files) && executeOpts.files.length > 0) {
-        const promises = executeOpts.files.map(async (fileObj) => {
+      if (isBatchOperation && executeOpts?.files && Array.isArray(executeOpts.files) && executeOpts.files.length > 0) {
+        const responses = await processBatch(executeOpts.files, async (fileObj, index) => {
           return $fetch(basePath, {
             baseURL: fullBaseURL,
             method,
@@ -95,7 +247,6 @@ export function useEnfyraApi(path, opts = {}) {
             query: finalQuery
           });
         });
-        const responses = await Promise.all(promises);
         data.value = responses;
         return responses;
       }

package/dist/index.d.ts

@@ -9,7 +9,37 @@ export interface ApiError {
     data?: any;
     response?: any;
 }
-export interface ApiOptions<T> {
+export interface BatchProgress {
+    /** Current progress percentage (0-100) */
+    progress: number;
+    /** Number of completed operations */
+    completed: number;
+    /** Total number of operations */
+    total: number;
+    /** Number of failed operations */
+    failed: number;
+    /** Number of operations currently in progress */
+    inProgress: number;
+    /** Estimated time remaining in milliseconds */
+    estimatedTimeRemaining?: number;
+    /** Average time per operation in milliseconds */
+    averageTime?: number;
+    /** Current batch being processed */
+    currentBatch: number;
+    /** Total number of batches */
+    totalBatches: number;
+    /** Processing speed (operations per second) */
+    operationsPerSecond?: number;
+    /** Detailed results array for completed operations */
+    results: Array<{
+        index: number;
+        status: 'completed' | 'failed';
+        result?: any;
+        error?: ApiError;
+        duration?: number;
+    }>;
+}
+interface BaseApiOptions<T> {
     method?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     body?: any;
     query?: Record<string, any>;
@@ -23,6 +53,22 @@ export interface ApiOptions<T> {
     /** Unique key for useFetch caching */
     key?: string;
 }
+interface BatchApiOptions {
+    /** Batch size for chunking large operations (default: no limit) - Only available for batch operations */
+    batchSize?: number;
+    /** Maximum concurrent requests (default: no limit) - Only available for batch operations */
+    concurrent?: number;
+    /** Real-time progress callback for batch operations - Only available for batch operations */
+    onProgress?: (progress: BatchProgress) => void;
+}
+type ConditionalBatchOptions<T> = T extends {
+    method?: 'patch' | 'delete' | 'PATCH' | 'DELETE';
+} ? BatchApiOptions : T extends {
+    method?: 'post' | 'POST';
+} ? BatchApiOptions : T extends {
+    method?: undefined;
+} ? Partial<BatchApiOptions> : {};
+export type ApiOptions<T> = BaseApiOptions<T> & ConditionalBatchOptions<BaseApiOptions<T>>;
 export interface BackendError {
     success: false;
     message: string;
@@ -46,16 +92,27 @@ export interface UseEnfyraApiSSRReturn<T> extends AsyncData<T | null, ApiError>
     error: Ref<ApiError | null>;
     refresh: () => Promise<void>;
 }
+interface BaseExecuteOptions {
+    body?: any;
+    id?: string | number;
+}
+interface BatchExecuteOptions {
+    ids?: (string | number)[];
+    /** Array of FormData objects for batch upload */
+    files?: FormData[];
+    /** Override batch size for this specific execution */
+    batchSize?: number;
+    /** Override concurrent limit for this specific execution */
+    concurrent?: number;
+    /** Override progress callback for this specific execution */
+    onProgress?: (progress: BatchProgress) => void;
+}
+export type ExecuteOptions = BaseExecuteOptions & BatchExecuteOptions;
 export interface UseEnfyraApiClientReturn<T> {
     data: Ref<T | null>;
     error: Ref<ApiError | null>;
     pending: Ref<boolean>;
-    execute: (executeOpts?: {
-        body?: any;
-        id?: string | number;
-        ids?: (string | number)[];
-        files?: any[];
-    }) => Promise<T | T[] | null>;
+    execute: (executeOpts?: ExecuteOptions) => Promise<T | T[] | null>;
 }
 export * from './auth';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/module.cjs

@@ -15,6 +15,16 @@ const module$1 = kit.defineNuxtModule({
   },
   setup(options, nuxt) {
     const { resolve } = kit.createResolver((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('module.cjs', document.baseURI).href)));
+    if (!options.apiUrl || !options.appUrl) {
+      throw new Error(
+        `[Enfyra SDK Nuxt] Missing required configuration:
+${!options.apiUrl ? "- apiUrl is required\n" : ""}${!options.appUrl ? "- appUrl is required\n" : ""}Please configure both in your nuxt.config.ts:
+enfyraSDK: {
+  apiUrl: 'https://your-api-url',
+  appUrl: 'https://your-app-url'
+}`
+      );
+    }
     nuxt.options.runtimeConfig.public.enfyraSDK = {
       ...nuxt.options.runtimeConfig.public.enfyraSDK,
       ...options

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@enfyra/sdk-nuxt",
   "configKey": "enfyraSDK",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "2.0.0"

package/dist/module.mjs

@@ -12,6 +12,16 @@ const module = defineNuxtModule({
   },
   setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
+    if (!options.apiUrl || !options.appUrl) {
+      throw new Error(
+        `[Enfyra SDK Nuxt] Missing required configuration:
+${!options.apiUrl ? "- apiUrl is required\n" : ""}${!options.appUrl ? "- appUrl is required\n" : ""}Please configure both in your nuxt.config.ts:
+enfyraSDK: {
+  apiUrl: 'https://your-api-url',
+  appUrl: 'https://your-app-url'
+}`
+      );
+    }
     nuxt.options.runtimeConfig.public.enfyraSDK = {
       ...nuxt.options.runtimeConfig.public.enfyraSDK,
       ...options

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfyra/sdk-nuxt",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Nuxt SDK for Enfyra CMS",
   "repository": {
     "type": "git",

package/src/composables/useEnfyraApi.ts

@@ -3,8 +3,10 @@ import type {
   ApiOptions,
   ApiError,
   BackendErrorExtended,
+  ExecuteOptions,
   UseEnfyraApiSSRReturn,
   UseEnfyraApiClientReturn,
+  BatchProgress,
 } from "../types";
 import { $fetch } from "../utils/http";
 import { useRuntimeConfig, useFetch, useRequestHeaders } from "#imports";
@@ -46,7 +48,7 @@ export function useEnfyraApi<T = any>(
   path: (() => string) | string,
   opts: ApiOptions<T> = {}
 ): UseEnfyraApiSSRReturn<T> | UseEnfyraApiClientReturn<T> {
-  const { method = "get", body, query, errorContext, onError, ssr, key } = opts;
+  const { method = "get", body, query, errorContext, onError, ssr, key, batchSize, concurrent, onProgress } = opts;
 
   // SSR mode - use useFetch
   if (ssr) {
@@ -101,12 +103,7 @@ export function useEnfyraApi<T = any>(
   const error = ref<ApiError | null>(null);
   const pending = ref(false);
 
-  const execute = async (executeOpts?: {
-    body?: any;
-    id?: string | number;
-    ids?: (string | number)[];
-    files?: any[];
-  }) => {
+  const execute = async (executeOpts?: ExecuteOptions) => {
     pending.value = true;
     error.value = null;
 
@@ -120,6 +117,20 @@ export function useEnfyraApi<T = any>(
         .replace(/^\/+/, ""); // Remove leading slashes
       const finalBody = executeOpts?.body || unref(body);
       const finalQuery = unref(query);
+      
+      // Check if this is actually a batch operation
+      const isBatchOperation = (
+        !opts.disableBatch && 
+        (
+          (executeOpts?.ids && executeOpts.ids.length > 0 && (method.toLowerCase() === "patch" || method.toLowerCase() === "delete")) ||
+          (method.toLowerCase() === "post" && executeOpts?.files && Array.isArray(executeOpts.files) && executeOpts.files.length > 0)
+        )
+      );
+
+      // Use batch options only if this is actually a batch operation
+      const effectiveBatchSize = isBatchOperation ? (executeOpts?.batchSize ?? batchSize) : undefined;
+      const effectiveConcurrent = isBatchOperation ? (executeOpts?.concurrent ?? concurrent) : undefined;
+      const effectiveOnProgress = isBatchOperation ? (executeOpts?.onProgress ?? onProgress) : undefined;
 
       // Helper function to build clean path
       const buildPath = (...segments: (string | number)[]): string => {
@@ -129,14 +140,205 @@ export function useEnfyraApi<T = any>(
       // Build full base URL with prefix
       const fullBaseURL = apiUrl + (apiPrefix || "");
 
+      // Helper function for batch processing with chunking, concurrency control, and real-time progress tracking
+      async function processBatch<T>(
+        items: any[],
+        processor: (item: any, index: number) => Promise<T>
+      ): Promise<T[]> {
+        const results: T[] = [];
+        const progressResults: BatchProgress['results'] = [];
+        const startTime = Date.now();
+        let completed = 0;
+        let failed = 0;
+        
+        // Calculate batch structure
+        const chunks = effectiveBatchSize ? 
+          Array.from({ length: Math.ceil(items.length / effectiveBatchSize) }, (_, i) =>
+            items.slice(i * effectiveBatchSize, i * effectiveBatchSize + effectiveBatchSize)
+          ) : [items];
+        
+        const totalBatches = chunks.length;
+        let currentBatch = 0;
+
+        // Initialize progress tracking
+        const updateProgress = (inProgress: number = 0) => {
+          if (effectiveOnProgress) {
+            const elapsed = Date.now() - startTime;
+            const progress = items.length > 0 ? Math.round((completed / items.length) * 100) : 0;
+            const averageTime = completed > 0 ? elapsed / completed : undefined;
+            const operationsPerSecond = completed > 0 ? (completed / elapsed) * 1000 : undefined;
+            const estimatedTimeRemaining = averageTime && items.length > completed 
+              ? Math.round(averageTime * (items.length - completed)) 
+              : undefined;
+
+            const progressData: BatchProgress = {
+              progress,
+              completed,
+              total: items.length,
+              failed,
+              inProgress,
+              estimatedTimeRemaining,
+              averageTime,
+              currentBatch: currentBatch + 1,
+              totalBatches,
+              operationsPerSecond,
+              results: [...progressResults]
+            };
+
+            effectiveOnProgress(progressData);
+          }
+        };
+
+        // Initial progress update
+        updateProgress(0);
+        
+        // If no limits, process all at once with progress tracking
+        if (!effectiveBatchSize && !effectiveConcurrent) {
+          updateProgress(items.length);
+          
+          const promises = items.map(async (item, index) => {
+            const itemStartTime = Date.now();
+            try {
+              const result = await processor(item, index);
+              const duration = Date.now() - itemStartTime;
+              
+              completed++;
+              progressResults.push({
+                index,
+                status: 'completed',
+                result,
+                duration
+              });
+              updateProgress(items.length - completed);
+              
+              return result;
+            } catch (error) {
+              const duration = Date.now() - itemStartTime;
+              failed++;
+              completed++;
+              
+              progressResults.push({
+                index,
+                status: 'failed',
+                error: error as ApiError,
+                duration
+              });
+              updateProgress(items.length - completed);
+              
+              throw error;
+            }
+          });
+          
+          const results = await Promise.all(promises);
+          updateProgress(0);
+          return results;
+        }
+
+        // Process each chunk with progress tracking
+        for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex++) {
+          currentBatch = chunkIndex;
+          const chunk = chunks[chunkIndex];
+          
+          if (effectiveConcurrent && chunk.length > effectiveConcurrent) {
+            // Process chunk with concurrency limit
+            for (let i = 0; i < chunk.length; i += effectiveConcurrent) {
+              const batch = chunk.slice(i, i + effectiveConcurrent);
+              const baseIndex = chunkIndex * (effectiveBatchSize || items.length) + i;
+              
+              updateProgress(batch.length);
+              
+              const batchPromises = batch.map(async (item, batchItemIndex) => {
+                const globalIndex = baseIndex + batchItemIndex;
+                const itemStartTime = Date.now();
+                
+                try {
+                  const result = await processor(item, globalIndex);
+                  const duration = Date.now() - itemStartTime;
+                  
+                  completed++;
+                  progressResults.push({
+                    index: globalIndex,
+                    status: 'completed',
+                    result,
+                    duration
+                  });
+                  updateProgress(Math.max(0, batch.length - (batchItemIndex + 1)));
+                  
+                  return result;
+                } catch (error) {
+                  const duration = Date.now() - itemStartTime;
+                  failed++;
+                  completed++;
+                  
+                  progressResults.push({
+                    index: globalIndex,
+                    status: 'failed',
+                    error: error as ApiError,
+                    duration
+                  });
+                  updateProgress(Math.max(0, batch.length - (batchItemIndex + 1)));
+                  
+                  throw error;
+                }
+              });
+              
+              const batchResults = await Promise.all(batchPromises);
+              results.push(...batchResults);
+            }
+          } else {
+            // Process entire chunk at once
+            const baseIndex = chunkIndex * (effectiveBatchSize || items.length);
+            
+            updateProgress(chunk.length);
+            
+            const chunkPromises = chunk.map(async (item, chunkItemIndex) => {
+              const globalIndex = baseIndex + chunkItemIndex;
+              const itemStartTime = Date.now();
+              
+              try {
+                const result = await processor(item, globalIndex);
+                const duration = Date.now() - itemStartTime;
+                
+                completed++;
+                progressResults.push({
+                  index: globalIndex,
+                  status: 'completed',
+                  result,
+                  duration
+                });
+                updateProgress(Math.max(0, chunk.length - (chunkItemIndex + 1)));
+                
+                return result;
+              } catch (error) {
+                const duration = Date.now() - itemStartTime;
+                failed++;
+                completed++;
+                
+                progressResults.push({
+                  index: globalIndex,
+                  status: 'failed',
+                  error: error as ApiError,
+                  duration
+                });
+                updateProgress(Math.max(0, chunk.length - (chunkItemIndex + 1)));
+                
+                throw error;
+              }
+            });
+            
+            const chunkResults = await Promise.all(chunkPromises);
+            results.push(...chunkResults);
+          }
+        }
+
+        // Final progress update
+        updateProgress(0);
+        return results;
+      }
+
       // Batch operation with multiple IDs (only for patch and delete)
-      if (
-        !opts.disableBatch &&
-        executeOpts?.ids &&
-        executeOpts.ids.length > 0 &&
-        (method.toLowerCase() === "patch" || method.toLowerCase() === "delete")
-      ) {
-        const promises = executeOpts.ids.map(async (id) => {
+      if (isBatchOperation && executeOpts?.ids && executeOpts.ids.length > 0) {
+        const responses = await processBatch(executeOpts.ids, async (id, index) => {
           const finalPath = buildPath(basePath, id);
           return $fetch<T>(finalPath, {
             baseURL: fullBaseURL,
@@ -147,20 +349,13 @@ export function useEnfyraApi<T = any>(
           });
         });
 
-        const responses = await Promise.all(promises);
         data.value = responses as T;
         return responses;
       }
 
       // Batch operation with files array for POST method
-      if (
-        !opts.disableBatch &&
-        method.toLowerCase() === "post" &&
-        executeOpts?.files &&
-        Array.isArray(executeOpts.files) &&
-        executeOpts.files.length > 0
-      ) {
-        const promises = executeOpts.files.map(async (fileObj: any) => {
+      if (isBatchOperation && executeOpts?.files && Array.isArray(executeOpts.files) && executeOpts.files.length > 0) {
+        const responses = await processBatch(executeOpts.files, async (fileObj: any, index) => {
           return $fetch<T>(basePath, {
             baseURL: fullBaseURL,
             method: method as any,
@@ -170,7 +365,6 @@ export function useEnfyraApi<T = any>(
           });
         });
 
-        const responses = await Promise.all(promises);
         data.value = responses as T;
         return responses;
       }

package/src/module.ts

@@ -18,6 +18,20 @@ export default defineNuxtModule({
   setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
 
+    // Validate required configuration
+    if (!options.apiUrl || !options.appUrl) {
+      throw new Error(
+        `[Enfyra SDK Nuxt] Missing required configuration:\n` +
+        `${!options.apiUrl ? '- apiUrl is required\n' : ''}` +
+        `${!options.appUrl ? '- appUrl is required\n' : ''}` +
+        `Please configure both in your nuxt.config.ts:\n` +
+        `enfyraSDK: {\n` +
+        `  apiUrl: 'https://your-api-url',\n` +
+        `  appUrl: 'https://your-app-url'\n` +
+        `}`
+      );
+    }
+
     // Make module options available at runtime
     nuxt.options.runtimeConfig.public.enfyraSDK = {
       ...nuxt.options.runtimeConfig.public.enfyraSDK,

package/src/types/index.ts

@@ -11,7 +11,39 @@ export interface ApiError {
   response?: any;
 }
 
-export interface ApiOptions<T> {
+export interface BatchProgress {
+  /** Current progress percentage (0-100) */
+  progress: number;
+  /** Number of completed operations */
+  completed: number;
+  /** Total number of operations */
+  total: number;
+  /** Number of failed operations */
+  failed: number;
+  /** Number of operations currently in progress */
+  inProgress: number;
+  /** Estimated time remaining in milliseconds */
+  estimatedTimeRemaining?: number;
+  /** Average time per operation in milliseconds */
+  averageTime?: number;
+  /** Current batch being processed */
+  currentBatch: number;
+  /** Total number of batches */
+  totalBatches: number;
+  /** Processing speed (operations per second) */
+  operationsPerSecond?: number;
+  /** Detailed results array for completed operations */
+  results: Array<{
+    index: number;
+    status: 'completed' | 'failed';
+    result?: any;
+    error?: ApiError;
+    duration?: number;
+  }>;
+}
+
+// Base options available for all operations
+interface BaseApiOptions<T> {
   method?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   body?: any;
   query?: Record<string, any>;
@@ -26,6 +58,28 @@ export interface ApiOptions<T> {
   key?: string;
 }
 
+// Batch-specific options (only available for batch operations)
+interface BatchApiOptions {
+  /** Batch size for chunking large operations (default: no limit) - Only available for batch operations */
+  batchSize?: number;
+  /** Maximum concurrent requests (default: no limit) - Only available for batch operations */
+  concurrent?: number;
+  /** Real-time progress callback for batch operations - Only available for batch operations */
+  onProgress?: (progress: BatchProgress) => void;
+}
+
+// Conditional type that adds batch options only for batch-capable methods
+type ConditionalBatchOptions<T> = T extends { method?: 'patch' | 'delete' | 'PATCH' | 'DELETE' }
+  ? BatchApiOptions
+  : T extends { method?: 'post' | 'POST' }
+  ? BatchApiOptions  // POST supports file batch uploads
+  : T extends { method?: undefined } // Default method is 'get', but could be overridden at execution
+  ? Partial<BatchApiOptions>  // Allow batch options but make them optional since method could change
+  : {};
+
+// Main ApiOptions interface with conditional batch support
+export type ApiOptions<T> = BaseApiOptions<T> & ConditionalBatchOptions<BaseApiOptions<T>>;
+
 export interface BackendError {
   success: false;
   message: string;
@@ -54,17 +108,41 @@ export interface UseEnfyraApiSSRReturn<T> extends AsyncData<T | null, ApiError>
   refresh: () => Promise<void>;
 }
 
+// Execute options interface
+// Base execute options available for all operations
+interface BaseExecuteOptions {
+  body?: any;
+  id?: string | number;
+}
+
+// Batch execute options (only available when doing batch operations)
+interface BatchExecuteOptions {
+  ids?: (string | number)[];
+  /** Array of FormData objects for batch upload */
+  files?: FormData[];
+  /** Override batch size for this specific execution */
+  batchSize?: number;
+  /** Override concurrent limit for this specific execution */
+  concurrent?: number;
+  /** Override progress callback for this specific execution */
+  onProgress?: (progress: BatchProgress) => void;
+}
+
+// Conditional execute options based on what's being executed
+type ConditionalExecuteOptions<T> = T extends { ids: any }
+  ? BatchExecuteOptions // If ids provided, enable all batch options
+  : T extends { files: any }
+  ? BatchExecuteOptions // If files provided, enable all batch options  
+  : BaseExecuteOptions & Partial<BatchExecuteOptions>; // Otherwise base options + optional batch options
+
+export type ExecuteOptions = BaseExecuteOptions & BatchExecuteOptions;
+
 // Client Mode return type
 export interface UseEnfyraApiClientReturn<T> {
   data: Ref<T | null>;
   error: Ref<ApiError | null>;
   pending: Ref<boolean>;
-  execute: (executeOpts?: {
-    body?: any;
-    id?: string | number;
-    ids?: (string | number)[];
-    files?: any[];
-  }) => Promise<T | T[] | null>;
+  execute: (executeOpts?: ExecuteOptions) => Promise<T | T[] | null>;
 }