@enfyra/sdk-nuxt 0.2.0 → 0.2.2

package/README.md

@@ -24,17 +24,10 @@ Add the module to your `nuxt.config.ts`:
 
 ```typescript
 export default defineNuxtConfig({
-  modules: [
-    '@enfyra/sdk-nuxt'
-  ],
-  runtimeConfig: {
-    public: {
-      enfyraSDK: {
-        apiUrl: process.env.ENFYRA_API_URL || 'https://api.enfyra.com',
-        apiPrefix: '/api/v1', // Optional: API prefix
-        appUrl: process.env.ENFYRA_APP_URL || 'https://app.enfyra.com'
-      },
-    },
+  modules: ["@enfyra/sdk-nuxt"],
+  enfyraSDK: {
+    apiUrl: "http://localhost:1105",
+    appUrl: "http://localhost:3001",
   },
 })
 ```
@@ -46,10 +39,10 @@ export default defineNuxtConfig({
 ```typescript
 // pages/users.vue
 <script setup>
-// ✅ Automatic server-side rendering with caching
+// ✅ Automatic execution on server-side with caching (runs immediately, no execute() needed)
 const { data: users, pending, error, refresh } = useEnfyraApi('/users', {
   ssr: true,
-  key: 'users-list'
+  key: 'users-list' // Optional cache key
 });
 </script>
 
@@ -121,19 +114,21 @@ await logout();
 Main composable for API requests with both SSR and client-side support.
 
 ```typescript
-// SSR Mode - Automatic execution
+// SSR Mode - Runs immediately (like useFetch)
 const { data, pending, error, refresh } = useEnfyraApi('/endpoint', {
   ssr: true,
-  key: 'cache-key',
+  key: 'cache-key', // Optional
   method: 'get',
   query: { page: 1 }
 });
+// ⚠️  Returns useFetch result: { data, pending, error, refresh }
 
 // Client Mode - Manual execution  
 const { data, pending, error, execute } = useEnfyraApi('/endpoint', {
   method: 'post',
   errorContext: 'Create Resource'
 });
+// ⚠️  Returns custom result: { data, pending, error, execute }
 
 await execute({ 
   body: { name: 'New Item' },
@@ -142,20 +137,29 @@ await execute({
 ```
 
 **Options:**
-- `ssr?: boolean` - Enable server-side rendering mode
+- `ssr?: boolean` - Enable server-side rendering mode (executes immediately like useFetch)
 - `method?: 'get' | 'post' | 'patch' | 'delete'` - HTTP method
 - `body?: any` - Request body (POST/PATCH)
 - `query?: Record<string, any>` - URL query parameters
 - `headers?: Record<string, string>` - Custom headers
 - `errorContext?: string` - Error context for logging
-- `key?: string` - Cache key (SSR mode only)
+- `onError?: (error: ApiError, context?: string) => void` - Custom error handler
+- `batchSize?: number` - Batch size for chunking large operations (default: no limit)
+- `concurrent?: number` - Maximum concurrent requests (default: no limit)
+- `key?: string` - Cache key (SSR mode, optional)
 - `default?: () => T` - Default value (SSR mode only)
 
+**⚠️ 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):**
 - `id?: string | number` - Single resource ID
 - `ids?: (string | number)[]` - Batch operation IDs (PATCH/DELETE)
-- `files?: FormData[]` - Batch file upload (POST)
+- `files?: FormData[]` - Array of FormData objects for batch upload (POST)
 - `body?: any` - Override request body
+- `batchSize?: number` - Override batch size for this execution
+- `concurrent?: number` - Override concurrent limit for this execution
 
 ### `useEnfyraAuth()`
 
@@ -179,7 +183,7 @@ await fetchUser()                 // Refresh user data
 ### Batch Operations
 
 ```typescript
-// Batch delete multiple items
+// Basic batch delete - unlimited parallel requests
 const { execute: deleteItems } = useEnfyraApi('/items', {
   method: 'delete',
   errorContext: 'Delete Items'
@@ -187,14 +191,50 @@ const { execute: deleteItems } = useEnfyraApi('/items', {
 
 await deleteItems({ ids: ['1', '2', '3'] });
 
-// Batch file upload
-const { execute: uploadFiles } = useEnfyraApi('/files', {
-  method: 'post', 
+// Advanced batch operations with concurrency control
+const { execute: deleteMany } = useEnfyraApi('/users', {
+  method: 'delete',
+  batchSize: 10,      // Process 10 items at a time
+  concurrent: 3,      // Max 3 requests simultaneously
+  onError: (error, context) => toast.error(`${context}: ${error.message}`)
+});
+
+// Delete 100 users in controlled batches
+await deleteMany({ ids: Array.from({length: 100}, (_, i) => `user-${i}`) });
+
+// Override batch settings per execution
+const { execute: updateUsers } = useEnfyraApi('/users', {
+  method: 'patch',
+  batchSize: 20,     // Default: 20 per batch
+  concurrent: 5      // Default: 5 concurrent
+});
+
+// This execution uses different settings
+await updateUsers({ 
+  ids: largeUserList,
+  body: { status: 'active' },
+  batchSize: 50,     // Override: 50 per batch for this call
+  concurrent: 10     // Override: 10 concurrent for this call
+});
+
+// Batch file upload with progress control
+const { execute: uploadFiles } = useEnfyraApi('/file_definition', {
+  method: 'post',
+  batchSize: 5,      // Upload 5 files at a time
+  concurrent: 2,     // Max 2 uploads simultaneously
   errorContext: 'Upload Files'
 });
 
+// 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
 });
 ```
 
@@ -228,10 +268,10 @@ const users = computed(() => data.value?.data || []);
 const searchQuery = ref('');
 const page = ref(1);
 
-// SSR mode with reactive query
+// SSR mode with reactive query (executes immediately)
 const { data, refresh } = useEnfyraApi('/users', {
   ssr: true,
-  key: () => `users-${page.value}-${searchQuery.value}`,
+  key: () => `users-${page.value}-${searchQuery.value}`, // Optional
   query: computed(() => ({
     search: searchQuery.value,
     page: page.value,
@@ -247,7 +287,7 @@ watch([searchQuery, page], () => refresh());
 
 For comprehensive guides and examples:
 
-📚 **[useEnfyraApi Complete Guide](./docs/useEnfyraApi.md)** - Detailed documentation with examples, best practices, and troubleshooting
+📚 **[useEnfyraApi Complete Guide](https://github.com/dothinh115/enfyra-sdk-nuxt/blob/main/docs/useEnfyraApi.md)** - Detailed documentation with examples, best practices, and troubleshooting
 
 Key topics covered:
 - SSR vs Client Mode comparison
@@ -260,30 +300,21 @@ Key topics covered:
 
 ## Configuration
 
-### Runtime Config Options
+### Module Options
 
 ```typescript
 // nuxt.config.ts
 export default defineNuxtConfig({
-  runtimeConfig: {
-    public: {
-      enfyraSDK: {
-        // Required: Main API URL
-        apiUrl: process.env.ENFYRA_API_URL,
-        
-        // Optional: API path prefix (default: '')
-        apiPrefix: '/api/v1',
-        
-        // Required: App URL for SSR requests
-        appUrl: process.env.ENFYRA_APP_URL,
-        
-        // Optional: Default headers for all requests
-        defaultHeaders: {
-          'Accept': 'application/json',
-          'Content-Type': 'application/json'
-        }
-      },
-    },
+  modules: ["@enfyra/sdk-nuxt"],
+  enfyraSDK: {
+    // Required: Main API URL
+    apiUrl: process.env.ENFYRA_API_URL || "http://localhost:1105",
+    
+    // Optional: API path prefix (default: '')
+    apiPrefix: '/api/v1',
+    
+    // Required: App URL for SSR requests  
+    appUrl: process.env.ENFYRA_APP_URL || "http://localhost:3001",
   },
 })
 ```
@@ -301,13 +332,13 @@ ENFYRA_APP_URL=https://app.enfyra.com
 ### 1. Choose the Right Mode
 
 ```typescript
-// ✅ Use SSR for initial page data
+// ✅ Use SSR for initial page data (runs immediately)
 const { data } = useEnfyraApi('/dashboard', {
   ssr: true,
-  key: 'dashboard'
+  key: 'dashboard' // Optional
 });
 
-// ✅ Use Client mode for user interactions
+// ✅ Use Client mode for user interactions (manual execution)
 const { execute: saveData } = useEnfyraApi('/settings', {
   method: 'patch',
   errorContext: 'Save Settings'  
@@ -370,11 +401,11 @@ Pull requests are welcome! Please read our contributing guidelines and ensure te
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) for a detailed history of changes and migration guides.
+See [CHANGELOG.md](https://github.com/dothinh115/enfyra-sdk-nuxt/blob/main/CHANGELOG.md) for a detailed history of changes and migration guides.
 
 ## Support
 
 For issues and questions:
-- 📖 Check the [detailed documentation](./docs/useEnfyraApi.md)
-- 🐛 [Report bugs](https://github.com/enfyra/sdk-nuxt/issues)
-- 💬 [Join our community](https://discord.gg/enfyra)
+- 📖 Check the [detailed documentation](https://github.com/dothinh115/enfyra-sdk-nuxt/blob/main/docs/useEnfyraApi.md)
+- 🐛 [Report bugs](https://github.com/dothinh115/enfyra-sdk-nuxt/issues)
+- 💬 [GitHub Discussions](https://github.com/dothinh115/enfyra-sdk-nuxt/discussions)

package/dist/composables/useEnfyraApi.d.ts

@@ -1,2 +1,12 @@
-import type { ApiOptions, UseEnfyraApiReturn } from "../types";
-export declare function useEnfyraApi<T = any>(path: (() => string) | string, opts?: ApiOptions<T>): UseEnfyraApiReturn<T>;
+import type { ApiOptions, UseEnfyraApiSSRReturn, UseEnfyraApiClientReturn } from "../types";
+
+// Function overloads for proper TypeScript support
+export declare function useEnfyraApi<T = any>(
+    path: (() => string) | string,
+    opts: ApiOptions<T> & { ssr: true }
+): UseEnfyraApiSSRReturn<T>;
+
+export declare function useEnfyraApi<T = any>(
+    path: (() => string) | string,  
+    opts?: ApiOptions<T> & { ssr?: false | undefined }
+): UseEnfyraApiClientReturn<T>;

package/dist/composables/useEnfyraApi.mjs

@@ -1,39 +1,22 @@
 import { ref, unref, toRaw } from "vue";
 import { $fetch } from "../utils/http";
 import { useRuntimeConfig, useFetch, useRequestHeaders } from "#imports";
-function handleApiError(error, context) {
-  let message = "Request failed";
-  let errorCode = "UNKNOWN_ERROR";
-  let correlationId;
-  if (error?.response?.data) {
-    const responseData = error.response.data;
-    if (responseData.error) {
-      message = responseData.error.message || responseData.message || "Request failed";
-      errorCode = responseData.error.code;
-      correlationId = responseData.error.correlationId;
-    } else {
-      message = responseData.message || "Request failed";
-    }
-  } else if (error?.data) {
-    const errorData = error.data;
-    if (errorData.error) {
-      message = errorData.error.message || errorData.message || "Request failed";
-      errorCode = errorData.error.code;
-      correlationId = errorData.error.correlationId;
-    } else {
-      message = errorData.message || "Request failed";
-    }
-  } else if (error?.message) {
-    message = error.message;
+function handleError(error, context, customHandler) {
+  const apiError = {
+    message: error?.message || error?.data?.message || "Request failed",
+    status: error?.status || error?.response?.status,
+    data: error?.data || error?.response?.data,
+    response: error?.response || error
+  };
+  if (customHandler) {
+    customHandler(apiError, context);
+  } else {
+    console.error(`[Enfyra API Error]`, { error: apiError, context });
   }
-  console.error(`[Enfyra API Error] ${errorCode}: ${message}`, {
-    context,
-    correlationId,
-    error
-  });
+  return apiError;
 }
 export function useEnfyraApi(path, opts = {}) {
-  const { method = "get", body, query, errorContext, ssr, key } = opts;
+  const { method = "get", body, query, errorContext, onError, ssr, key, batchSize, concurrent } = opts;
   if (ssr) {
     const config = useRuntimeConfig().public.enfyraSDK;
     const basePath = (typeof path === "function" ? path() : path).replace(/^\/?api\/?/, "").replace(/^\/+/, "");
@@ -82,12 +65,38 @@ 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 effectiveBatchSize = executeOpts?.batchSize ?? batchSize;
+      const effectiveConcurrent = executeOpts?.concurrent ?? concurrent;
       const buildPath = (...segments) => {
         return segments.filter(Boolean).join("/");
       };
       const fullBaseURL = apiUrl + (apiPrefix || "");
+      async function processBatch(items, processor) {
+        const results = [];
+        if (!effectiveBatchSize && !effectiveConcurrent) {
+          const promises = items.map(processor);
+          return await Promise.all(promises);
+        }
+        const chunks = effectiveBatchSize ? Array.from(
+          { length: Math.ceil(items.length / effectiveBatchSize) },
+          (_, i) => items.slice(i * effectiveBatchSize, i * effectiveBatchSize + effectiveBatchSize)
+        ) : [items];
+        for (const chunk of chunks) {
+          if (effectiveConcurrent && chunk.length > effectiveConcurrent) {
+            for (let i = 0; i < chunk.length; i += effectiveConcurrent) {
+              const batch = chunk.slice(i, i + effectiveConcurrent);
+              const batchResults = await Promise.all(batch.map(processor));
+              results.push(...batchResults);
+            }
+          } else {
+            const chunkResults = await Promise.all(chunk.map(processor));
+            results.push(...chunkResults);
+          }
+        }
+        return results;
+      }
       if (!opts.disableBatch && executeOpts?.ids && executeOpts.ids.length > 0 && (method.toLowerCase() === "patch" || method.toLowerCase() === "delete")) {
-        const promises = executeOpts.ids.map(async (id) => {
+        const responses = await processBatch(executeOpts.ids, async (id) => {
           const finalPath2 = buildPath(basePath, id);
           return $fetch(finalPath2, {
             baseURL: fullBaseURL,
@@ -97,12 +106,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) => {
+        const responses = await processBatch(executeOpts.files, async (fileObj) => {
           return $fetch(basePath, {
             baseURL: fullBaseURL,
             method,
@@ -112,7 +120,6 @@ export function useEnfyraApi(path, opts = {}) {
             query: finalQuery
           });
         });
-        const responses = await Promise.all(promises);
         data.value = responses;
         return responses;
       }
@@ -127,8 +134,8 @@ export function useEnfyraApi(path, opts = {}) {
       data.value = response;
       return response;
     } catch (err) {
-      error.value = err;
-      handleApiError(err, errorContext);
+      const apiError = handleError(err, errorContext, onError);
+      error.value = apiError;
       return null;
     } finally {
       pending.value = false;

package/dist/composables.d.ts

@@ -1,5 +1,6 @@
 import type { Ref, ComputedRef } from 'vue';
-import type { LoginPayload, User, ApiOptions, UseEnfyraApiReturn } from './index';
+import type { LoginPayload, User, ApiOptions, UseEnfyraApiSSRReturn, UseEnfyraApiClientReturn } from './index';
+
 export declare function useEnfyraAuth(): {
     me: Ref<User | null>;
     login: (payload: LoginPayload) => Promise<any>;
@@ -7,5 +8,14 @@ export declare function useEnfyraAuth(): {
     fetchUser: () => Promise<void>;
     isLoggedIn: ComputedRef<boolean>;
 };
-export declare function useEnfyraApi<T = any>(path: (() => string) | string, opts?: ApiOptions<T>): UseEnfyraApiReturn<T>;
-//# sourceMappingURL=composables.d.ts.map
+
+// Function overloads for proper TypeScript support
+export declare function useEnfyraApi<T = any>(
+    path: (() => string) | string,
+    opts: ApiOptions<T> & { ssr: true }
+): UseEnfyraApiSSRReturn<T>;
+
+export declare function useEnfyraApi<T = any>(
+    path: (() => string) | string,
+    opts?: ApiOptions<T> & { ssr?: false | undefined }
+): UseEnfyraApiClientReturn<T>;

package/dist/index.d.ts

@@ -3,13 +3,24 @@ export interface EnfyraConfig {
     apiPrefix?: string;
     defaultHeaders?: Record<string, string>;
 }
+export interface ApiError {
+    message: string;
+    status?: number;
+    data?: any;
+    response?: any;
+}
 export interface ApiOptions<T> {
     method?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     body?: any;
     query?: Record<string, any>;
     headers?: Record<string, string>;
     errorContext?: string;
+    onError?: (error: ApiError, context?: string) => void;
     disableBatch?: boolean;
+    /** Batch size for chunking large operations (default: no limit) */
+    batchSize?: number;
+    /** Maximum concurrent requests (default: no limit) */
+    concurrent?: number;
     default?: () => T;
     /** Enable SSR with useFetch instead of $fetch */
     ssr?: boolean;
@@ -32,17 +43,29 @@ export interface BackendErrorExtended extends BackendError {
     };
 }
 import type { Ref } from 'vue';
-export interface UseEnfyraApiReturn<T> {
+import type { AsyncData } from 'nuxt/app';
+export interface UseEnfyraApiSSRReturn<T> extends AsyncData<T | null, ApiError> {
+    data: Ref<T | null>;
+    pending: Ref<boolean>;
+    error: Ref<ApiError | null>;
+    refresh: () => Promise<void>;
+}
+export interface ExecuteOptions {
+    body?: any;
+    id?: string | number;
+    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;
+}
+export interface UseEnfyraApiClientReturn<T> {
     data: Ref<T | null>;
-    error: Ref<any>;
+    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';
-export * from './composables';
 //# 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":"AAAA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACnG,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACpB,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IACtB,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE;QACtB,IAAI,CAAC,EAAE,GAAG,CAAC;QACX,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACrB,GAAG,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;KACf,KAAK,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;CAC/B;AAGD,cAAc,QAAQ,CAAC;AAGvB,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,2 @@
 // Re-export auth types
 export * from './auth';
-// Re-export composables types
-export * from './composables';

package/dist/module.json

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

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@enfyra/sdk-nuxt",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Nuxt SDK for Enfyra CMS",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dothinh115/enfyra-sdk-nuxt.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dothinh115/enfyra-sdk-nuxt/issues"
+  },
+  "homepage": "https://github.com/dothinh115/enfyra-sdk-nuxt#readme",
   "main": "./dist/module.mjs",
   "types": "./dist/index.d.ts",
   "exports": {

package/src/composables/useEnfyraApi.ts

@@ -1,56 +1,53 @@
 import { ref, unref, toRaw } from "vue";
 import type {
   ApiOptions,
+  ApiError,
   BackendErrorExtended,
-  UseEnfyraApiReturn,
+  ExecuteOptions,
+  UseEnfyraApiSSRReturn,
+  UseEnfyraApiClientReturn,
 } from "../types";
 import { $fetch } from "../utils/http";
 import { useRuntimeConfig, useFetch, useRequestHeaders } from "#imports";
 
-function handleApiError(error: any, context?: string) {
-  let message = "Request failed";
-  let errorCode = "UNKNOWN_ERROR";
-  let correlationId: string | undefined;
-
-  // Handle backend error response format
-  if (error?.response?.data) {
-    const responseData = error.response.data as BackendErrorExtended;
-    if (responseData.error) {
-      message =
-        responseData.error.message || responseData.message || "Request failed";
-      errorCode = responseData.error.code;
-      correlationId = responseData.error.correlationId;
-    } else {
-      message = responseData.message || "Request failed";
-    }
-  } else if (error?.data) {
-    const errorData = error.data as BackendErrorExtended;
-    if (errorData.error) {
-      message =
-        errorData.error.message || errorData.message || "Request failed";
-      errorCode = errorData.error.code;
-      correlationId = errorData.error.correlationId;
-    } else {
-      message = errorData.message || "Request failed";
-    }
-  } else if (error?.message) {
-    message = error.message;
+function handleError(
+  error: any,
+  context?: string,
+  customHandler?: (error: ApiError, context?: string) => void
+) {
+  // Transform error to ApiError format
+  const apiError: ApiError = {
+    message: error?.message || error?.data?.message || "Request failed",
+    status: error?.status || error?.response?.status,
+    data: error?.data || error?.response?.data,
+    response: error?.response || error
+  };
+
+  if (customHandler) {
+    customHandler(apiError, context);
+  } else {
+    console.error(`[Enfyra API Error]`, { error: apiError, context });
   }
 
-  // You can customize error handling here
-  // For now, just log the error
-  console.error(`[Enfyra API Error] ${errorCode}: ${message}`, {
-    context,
-    correlationId,
-    error,
-  });
+  return apiError;
 }
 
+// Function overloads for proper TypeScript support
+export function useEnfyraApi<T = any>(
+  path: (() => string) | string,
+  opts: ApiOptions<T> & { ssr: true }
+): UseEnfyraApiSSRReturn<T>;
+
+export function useEnfyraApi<T = any>(
+  path: (() => string) | string,
+  opts?: ApiOptions<T> & { ssr?: false | undefined }
+): UseEnfyraApiClientReturn<T>;
+
 export function useEnfyraApi<T = any>(
   path: (() => string) | string,
   opts: ApiOptions<T> = {}
-): UseEnfyraApiReturn<T> {
-  const { method = "get", body, query, errorContext, ssr, key } = opts;
+): UseEnfyraApiSSRReturn<T> | UseEnfyraApiClientReturn<T> {
+  const { method = "get", body, query, errorContext, onError, ssr, key, batchSize, concurrent } = opts;
 
   // SSR mode - use useFetch
   if (ssr) {
@@ -99,18 +96,13 @@ export function useEnfyraApi<T = any>(
       fetchOptions.default = opts.default;
     }
 
-    return useFetch<T>(finalUrl, fetchOptions) as any;
+    return useFetch<T>(finalUrl, fetchOptions) as UseEnfyraApiSSRReturn<T>;
   }
   const data = ref<T | null>(null);
-  const error = ref<any>(null);
+  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;
 
@@ -124,6 +116,10 @@ export function useEnfyraApi<T = any>(
         .replace(/^\/+/, ""); // Remove leading slashes
       const finalBody = executeOpts?.body || unref(body);
       const finalQuery = unref(query);
+      
+      // Use executeOpts overrides if provided, otherwise fall back to options
+      const effectiveBatchSize = executeOpts?.batchSize ?? batchSize;
+      const effectiveConcurrent = executeOpts?.concurrent ?? concurrent;
 
       // Helper function to build clean path
       const buildPath = (...segments: (string | number)[]): string => {
@@ -133,6 +129,44 @@ export function useEnfyraApi<T = any>(
       // Build full base URL with prefix
       const fullBaseURL = apiUrl + (apiPrefix || "");
 
+      // Helper function for batch processing with chunking and concurrency control
+      async function processBatch<T>(
+        items: any[],
+        processor: (item: any) => Promise<T>
+      ): Promise<T[]> {
+        const results: T[] = [];
+        
+        // If no limits, process all at once (current behavior)
+        if (!effectiveBatchSize && !effectiveConcurrent) {
+          const promises = items.map(processor);
+          return await Promise.all(promises);
+        }
+
+        // Chunk items by batchSize
+        const chunks = effectiveBatchSize ? 
+          Array.from({ length: Math.ceil(items.length / effectiveBatchSize) }, (_, i) =>
+            items.slice(i * effectiveBatchSize, i * effectiveBatchSize + effectiveBatchSize)
+          ) : [items];
+
+        // Process each chunk
+        for (const chunk of chunks) {
+          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 batchResults = await Promise.all(batch.map(processor));
+              results.push(...batchResults);
+            }
+          } else {
+            // Process entire chunk at once
+            const chunkResults = await Promise.all(chunk.map(processor));
+            results.push(...chunkResults);
+          }
+        }
+
+        return results;
+      }
+
       // Batch operation with multiple IDs (only for patch and delete)
       if (
         !opts.disableBatch &&
@@ -140,7 +174,7 @@ export function useEnfyraApi<T = any>(
         executeOpts.ids.length > 0 &&
         (method.toLowerCase() === "patch" || method.toLowerCase() === "delete")
       ) {
-        const promises = executeOpts.ids.map(async (id) => {
+        const responses = await processBatch(executeOpts.ids, async (id) => {
           const finalPath = buildPath(basePath, id);
           return $fetch<T>(finalPath, {
             baseURL: fullBaseURL,
@@ -151,7 +185,6 @@ export function useEnfyraApi<T = any>(
           });
         });
 
-        const responses = await Promise.all(promises);
         data.value = responses as T;
         return responses;
       }
@@ -164,7 +197,7 @@ export function useEnfyraApi<T = any>(
         Array.isArray(executeOpts.files) &&
         executeOpts.files.length > 0
       ) {
-        const promises = executeOpts.files.map(async (fileObj: any) => {
+        const responses = await processBatch(executeOpts.files, async (fileObj: any) => {
           return $fetch<T>(basePath, {
             baseURL: fullBaseURL,
             method: method as any,
@@ -174,7 +207,6 @@ export function useEnfyraApi<T = any>(
           });
         });
 
-        const responses = await Promise.all(promises);
         data.value = responses as T;
         return responses;
       }
@@ -195,8 +227,8 @@ export function useEnfyraApi<T = any>(
       data.value = response;
       return response;
     } catch (err) {
-      error.value = err;
-      handleApiError(err, errorContext);
+      const apiError = handleError(err, errorContext, onError);
+      error.value = apiError;
       return null;
     } finally {
       pending.value = false;
@@ -204,9 +236,9 @@ export function useEnfyraApi<T = any>(
   };
 
   return {
-    data: data as any,
+    data,
     error,
     pending,
     execute,
-  };
+  } as UseEnfyraApiClientReturn<T>;
 }

package/src/types/index.ts

@@ -4,13 +4,25 @@ export interface EnfyraConfig {
   defaultHeaders?: Record<string, string>;
 }
 
+export interface ApiError {
+  message: string;
+  status?: number;
+  data?: any;
+  response?: any;
+}
+
 export interface ApiOptions<T> {
   method?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   body?: any;
   query?: Record<string, any>;
   headers?: Record<string, string>;
   errorContext?: string;
+  onError?: (error: ApiError, context?: string) => void;
   disableBatch?: boolean;
+  /** Batch size for chunking large operations (default: no limit) */
+  batchSize?: number;
+  /** Maximum concurrent requests (default: no limit) */
+  concurrent?: number;
   default?: () => T;
   /** Enable SSR with useFetch instead of $fetch */
   ssr?: boolean;
@@ -36,21 +48,38 @@ export interface BackendErrorExtended extends BackendError {
 }
 
 import type { Ref } from 'vue';
+import type { AsyncData } from 'nuxt/app';
 
-export interface UseEnfyraApiReturn<T> {
+// SSR Mode return type (same as useFetch)
+export interface UseEnfyraApiSSRReturn<T> extends AsyncData<T | null, ApiError> {
   data: Ref<T | null>;
-  error: Ref<any>;
   pending: Ref<boolean>;
-  execute: (executeOpts?: {
-    body?: any;
-    id?: string | number;
-    ids?: (string | number)[];
-    files?: any[];
-  }) => Promise<T | T[] | null>;
+  error: Ref<ApiError | null>;
+  refresh: () => Promise<void>;
+}
+
+// Execute options interface
+export interface ExecuteOptions {
+  body?: any;
+  id?: string | number;
+  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;
 }
 
+// Client Mode return type
+export interface UseEnfyraApiClientReturn<T> {
+  data: Ref<T | null>;
+  error: Ref<ApiError | null>;
+  pending: Ref<boolean>;
+  execute: (executeOpts?: ExecuteOptions) => Promise<T | T[] | null>;
+}
+
+
 // Re-export auth types
 export * from './auth';
 
-// Re-export composables types
-export * from './composables';

package/dist/composables.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"composables.d.ts","sourceRoot":"","sources":["../src/types/composables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,KAAK,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEjF,MAAM,CAAC,OAAO,UAAU,aAAa,IAAI;IACvC,EAAE,EAAE,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAA;IACpB,KAAK,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;IAC9C,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CACjC,CAAA;AAED,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,CAAC,GAAG,GAAG,EAC1C,IAAI,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,MAAM,EAC7B,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GACnB,kBAAkB,CAAC,CAAC,CAAC,CAAA"}

package/dist/composables.js

@@ -1 +0,0 @@
-export {};

package/src/types/composables.ts

@@ -1,15 +0,0 @@
-import type { Ref, ComputedRef } from 'vue'
-import type { LoginPayload, User, ApiOptions, UseEnfyraApiReturn } from './index'
-
-export declare function useEnfyraAuth(): {
-  me: Ref<User | null>
-  login: (payload: LoginPayload) => Promise<any>
-  logout: () => Promise<void>
-  fetchUser: () => Promise<void>
-  isLoggedIn: ComputedRef<boolean>
-}
-
-export declare function useEnfyraApi<T = any>(
-  path: (() => string) | string,
-  opts?: ApiOptions<T>
-): UseEnfyraApiReturn<T>