@enfyra/sdk-nuxt 0.1.13 → 0.2.1

package/README.md

@@ -1,6 +1,16 @@
 # @enfyra/sdk-nuxt
 
-Nuxt SDK for Enfyra CMS
+Nuxt SDK for Enfyra CMS - A powerful composable-based API client with full SSR support and TypeScript integration.
+
+## Features
+
+✅ **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)  
+✅ **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  
 
 ## Installation
 
@@ -8,37 +18,353 @@ Nuxt SDK for Enfyra CMS
 npm install @enfyra/sdk-nuxt
 ```
 
-## Usage
+## Setup
+
+Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ["@enfyra/sdk-nuxt"],
+  enfyraSDK: {
+    apiUrl: "http://localhost:1105",
+    appUrl: "http://localhost:3001",
+  },
+})
+```
+
+## Quick Start
+
+### SSR Mode - Perfect for Page Data
+
+```typescript
+// pages/users.vue
+<script setup>
+// ✅ 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' // Optional cache key
+});
+</script>
+
+<template>
+  <div>
+    <div v-if="pending">Loading users...</div>
+    <div v-else-if="error">Error: {{ error }}</div>
+    <div v-else>
+      <h1>Users ({{ users?.meta?.totalCount }})</h1>
+      <UserCard v-for="user in users?.data" :key="user.id" :user="user" />
+      <button @click="refresh">Refresh</button>
+    </div>
+  </div>
+</template>
+```
+
+### Client Mode - Perfect for User Interactions
+
+```typescript
+// components/CreateUserForm.vue  
+<script setup>
+// ✅ Manual execution control for form submissions
+const { execute: createUser, pending, error } = useEnfyraApi('/users', {
+  method: 'post',
+  errorContext: 'Create User'
+});
+
+const formData = reactive({
+  name: '',
+  email: ''
+});
+
+async function handleSubmit() {
+  await createUser({ body: formData });
+  
+  if (!error.value) {
+    toast.success('User created successfully!');
+    await navigateTo('/users');
+  }
+}
+</script>
+```
+
+### Authentication
+
+```typescript
+<script setup>
+const { me, login, logout, isLoggedIn } = useEnfyraAuth();
+
+// Login
+await login({
+  email: 'user@example.com',
+  password: 'password123'
+});
+
+// Check auth status
+console.log('Logged in:', isLoggedIn.value);
+console.log('Current user:', me.value);
+
+// Logout  
+await logout();
+</script>
+```
+
+## Core Composables
+
+### `useEnfyraApi<T>(path, options)`
+
+Main composable for API requests with both SSR and client-side support.
+
+```typescript
+// SSR Mode - Runs immediately (like useFetch)
+const { data, pending, error, refresh } = useEnfyraApi('/endpoint', {
+  ssr: true,
+  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' },
+  id: '123'  // For /endpoint/123
+});
+```
+
+**Options:**
+- `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, 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)
+- `body?: any` - Override request body
+
+### `useEnfyraAuth()`
+
+Authentication composable with reactive state management.
+
+```typescript
+const { me, login, logout, fetchUser, isLoggedIn } = useEnfyraAuth();
+
+// Properties
+me.value          // Current user data (reactive)
+isLoggedIn.value  // Auth status (computed)
+
+// Methods  
+await login({ email, password })  // Login user
+await logout()                    // Logout user  
+await fetchUser()                 // Refresh user data
+```
+
+## Advanced Usage
+
+### Batch Operations
+
+```typescript
+// Batch delete multiple items
+const { execute: deleteItems } = useEnfyraApi('/items', {
+  method: 'delete',
+  errorContext: 'Delete Items'
+});
+
+await deleteItems({ ids: ['1', '2', '3'] });
+
+// Batch file upload
+const { execute: uploadFiles } = useEnfyraApi('/files', {
+  method: 'post', 
+  errorContext: 'Upload Files'
+});
+
+await uploadFiles({ 
+  files: [formData1, formData2, formData3] 
+});
+```
+
+### TypeScript Integration
+
+```typescript
+// Define your API response types
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+interface ApiResponse<T> {
+  data: T[];
+  meta: { totalCount: number };
+}
+
+// Use with full type safety
+const { data } = useEnfyraApi<ApiResponse<User>>('/users', {
+  ssr: true
+});
+
+// TypeScript knows data.value is ApiResponse<User> | null
+const users = computed(() => data.value?.data || []);
+```
+
+### Reactive Parameters
+
+```typescript
+const searchQuery = ref('');
+const page = ref(1);
+
+// SSR mode with reactive query (executes immediately)
+const { data, refresh } = useEnfyraApi('/users', {
+  ssr: true,
+  key: () => `users-${page.value}-${searchQuery.value}`, // Optional
+  query: computed(() => ({
+    search: searchQuery.value,
+    page: page.value,
+    limit: 10
+  }))
+});
+
+// Watch for changes and refresh
+watch([searchQuery, page], () => refresh());
+```
+
+## Documentation
+
+For comprehensive guides and examples:
+
+📚 **[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
+- Authentication and headers forwarding  
+- Batch operations and CRUD patterns
+- Error handling best practices
+- TypeScript integration
+- Performance optimization
+- Migration guides
+
+## Configuration
 
-Add to your `nuxt.config.ts`:
+### Module Options
 
 ```typescript
+// nuxt.config.ts
 export default defineNuxtConfig({
-  modules: [
-    '@enfyra/sdk-nuxt'
-  ],
-  runtimeConfig: {
-    public: {
-      enfyraSDK: {
-        appUrl: 'http://localhost:3000',
-        apiUrl: process.env.API_URL,
-        apiPrefix: '/api',
-      },
-    },
+  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",
   },
 })
 ```
 
-## Composables
+### Environment Variables
 
-### useEnfyraApi
+```bash
+# .env
+ENFYRA_API_URL=https://api.enfyra.com
+ENFYRA_APP_URL=https://app.enfyra.com
+```
+
+## Best Practices
+
+### 1. Choose the Right Mode
+
+```typescript
+// ✅ Use SSR for initial page data (runs immediately)
+const { data } = useEnfyraApi('/dashboard', {
+  ssr: true,
+  key: 'dashboard' // Optional
+});
+
+// ✅ Use Client mode for user interactions (manual execution)
+const { execute: saveData } = useEnfyraApi('/settings', {
+  method: 'patch',
+  errorContext: 'Save Settings'  
+});
+```
+
+### 2. Proper Error Handling
 
 ```typescript
-const { data, error, pending, execute } = useEnfyraApi('/users')
+// ✅ Check error state (don't use try-catch)
+async function handleSubmit() {
+  await execute({ body: formData });
+  
+  if (error.value) {
+    return; // Error already logged
+  }
+  
+  // Success handling
+  toast.success('Saved successfully');
+}
 ```
 
-### useEnfyraAuth
+### 3. Type Safety
 
 ```typescript
-const { me, login, logout, fetchUser } = useEnfyraAuth()
-```
+// ✅ Define interfaces for API responses
+interface CreateUserResponse {
+  data: User;
+  message: string;
+}
+
+const { execute } = useEnfyraApi<CreateUserResponse>('/users', {
+  method: 'post'
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Headers not forwarded in SSR** - Ensure `ssr: true` is set
+2. **Batch operations not working** - Only available in Client mode  
+3. **Data not reactive** - Use computed refs for reactive parameters
+4. **TypeScript errors** - Check return type differences between modes
+
+### Performance Tips
+
+- Use SSR for initial data loading (better SEO, faster page loads)
+- Use Client mode for user interactions (better UX)
+- Implement proper cache keys to avoid over-caching
+- Group related operations with batch APIs
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome! Please read our contributing guidelines and ensure tests pass.
+
+## Changelog
+
+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](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,57 @@
 import { ref, unref, toRaw } from "vue";
 import { $fetch } from "../utils/http";
-import { useRuntimeConfig } 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;
+import { useRuntimeConfig, useFetch, useRequestHeaders } from "#imports";
+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 } = opts;
+  const { method = "get", body, query, errorContext, onError, ssr, key } = opts;
+  if (ssr) {
+    const config = useRuntimeConfig().public.enfyraSDK;
+    const basePath = (typeof path === "function" ? path() : path).replace(/^\/?api\/?/, "").replace(/^\/+/, "");
+    const finalUrl = (config?.appUrl || "") + (config?.apiPrefix || "") + "/" + basePath;
+    const clientHeaders = process.client ? {} : useRequestHeaders([
+      "authorization",
+      "cookie",
+      "user-agent",
+      "accept",
+      "accept-language",
+      "referer"
+    ]);
+    const serverHeaders = { ...clientHeaders };
+    delete serverHeaders.connection;
+    delete serverHeaders["keep-alive"];
+    delete serverHeaders.host;
+    delete serverHeaders["content-length"];
+    const fetchOptions = {
+      method,
+      body,
+      query,
+      headers: {
+        ...serverHeaders,
+        ...opts.headers
+        // Custom headers override client headers
+      }
+    };
+    if (key) {
+      fetchOptions.key = key;
+    }
+    if (opts.default) {
+      fetchOptions.default = opts.default;
+    }
+    return useFetch(finalUrl, fetchOptions);
+  }
   const data = ref(null);
   const error = ref(null);
   const pending = ref(false);
@@ -92,8 +110,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,14 +3,25 @@ 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;
     default?: () => T;
+    /** Enable SSR with useFetch instead of $fetch */
+    ssr?: boolean;
+    /** Unique key for useFetch caching */
+    key?: string;
 }
 export interface BackendError {
     success: false;
@@ -28,9 +39,16 @@ 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 UseEnfyraApiClientReturn<T> {
     data: Ref<T | null>;
-    error: Ref<any>;
+    error: Ref<ApiError | null>;
     pending: Ref<boolean>;
     execute: (executeOpts?: {
         body?: any;
@@ -40,5 +58,4 @@ export interface UseEnfyraApiReturn<T> {
     }) => 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;CACnB;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.cjs

@@ -15,6 +15,10 @@ 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)));
+    nuxt.options.runtimeConfig.public.enfyraSDK = {
+      ...nuxt.options.runtimeConfig.public.enfyraSDK,
+      ...options
+    };
     kit.addImportsDir(resolve("./composables"));
     kit.addServerHandler({
       handler: resolve("./runtime/server/middleware/auth"),

package/dist/module.json

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

package/dist/module.mjs

@@ -12,6 +12,10 @@ const module = defineNuxtModule({
   },
   setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.enfyraSDK = {
+      ...nuxt.options.runtimeConfig.public.enfyraSDK,
+      ...options
+    };
     addImportsDir(resolve("./composables"));
     addServerHandler({
       handler: resolve("./runtime/server/middleware/auth"),

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@enfyra/sdk-nuxt",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "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,58 +1,104 @@
 import { ref, unref, toRaw } from "vue";
 import type {
   ApiOptions,
+  ApiError,
   BackendErrorExtended,
-  UseEnfyraApiReturn,
+  UseEnfyraApiSSRReturn,
+  UseEnfyraApiClientReturn,
 } from "../types";
 import { $fetch } from "../utils/http";
-import { useRuntimeConfig } 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;
+import { useRuntimeConfig, useFetch, useRequestHeaders } from "#imports";
+
+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 } = opts;
+): UseEnfyraApiSSRReturn<T> | UseEnfyraApiClientReturn<T> {
+  const { method = "get", body, query, errorContext, onError, ssr, key } = opts;
+
+  // SSR mode - use useFetch
+  if (ssr) {
+    const config = useRuntimeConfig().public.enfyraSDK;
+    const basePath = (typeof path === "function" ? path() : path)
+      .replace(/^\/?api\/?/, "")
+      .replace(/^\/+/, ""); // Remove leading slashes
+
+    const finalUrl =
+      (config?.appUrl || "") + (config?.apiPrefix || "") + "/" + basePath;
+
+    // Get headers from client request and filter out connection-specific headers
+    const clientHeaders = process.client
+      ? {}
+      : useRequestHeaders([
+          "authorization",
+          "cookie",
+          "user-agent",
+          "accept",
+          "accept-language",
+          "referer",
+        ]);
+
+    // Remove connection-specific headers that shouldn't be forwarded
+    const serverHeaders = { ...clientHeaders };
+    delete serverHeaders.connection;
+    delete serverHeaders["keep-alive"];
+    delete serverHeaders.host;
+    delete serverHeaders["content-length"];
+
+    const fetchOptions: any = {
+      method: method as any,
+      body: body,
+      query: query,
+      headers: {
+        ...serverHeaders,
+        ...opts.headers, // Custom headers override client headers
+      },
+    };
+
+    // Only add useFetch-specific options if provided
+    if (key) {
+      fetchOptions.key = key;
+    }
+    if (opts.default) {
+      fetchOptions.default = opts.default;
+    }
+
+    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?: {
@@ -69,7 +115,6 @@ export function useEnfyraApi<T = any>(
       const config: any = useRuntimeConfig().public.enfyraSDK;
       const apiUrl = config?.appUrl;
       const apiPrefix = config?.apiPrefix;
-
       const basePath = (typeof path === "function" ? path() : path)
         .replace(/^\/?api\/?/, "")
         .replace(/^\/+/, ""); // Remove leading slashes
@@ -146,8 +191,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;
@@ -155,9 +200,9 @@ export function useEnfyraApi<T = any>(
   };
 
   return {
-    data: data as any,
+    data,
     error,
     pending,
     execute,
-  };
+  } as UseEnfyraApiClientReturn<T>;
 }

package/src/module.ts

@@ -18,6 +18,12 @@ export default defineNuxtModule({
   setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
 
+    // Make module options available at runtime
+    nuxt.options.runtimeConfig.public.enfyraSDK = {
+      ...nuxt.options.runtimeConfig.public.enfyraSDK,
+      ...options,
+    };
+
     // Auto-import composables
     addImportsDir(resolve("./composables"));
 

package/src/types/index.ts

@@ -4,14 +4,26 @@ 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;
   default?: () => T;
+  /** Enable SSR with useFetch instead of $fetch */
+  ssr?: boolean;
+  /** Unique key for useFetch caching */
+  key?: string;
 }
 
 export interface BackendError {
@@ -32,10 +44,20 @@ export interface BackendErrorExtended extends BackendError {
 }
 
 import type { Ref } from 'vue';
+import type { AsyncData } from 'nuxt/app';
+
+// SSR Mode return type (same as useFetch)
+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 UseEnfyraApiReturn<T> {
+// Client Mode return type
+export interface UseEnfyraApiClientReturn<T> {
   data: Ref<T | null>;
-  error: Ref<any>;
+  error: Ref<ApiError | null>;
   pending: Ref<boolean>;
   execute: (executeOpts?: {
     body?: any;
@@ -45,8 +67,7 @@ export interface UseEnfyraApiReturn<T> {
   }) => 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>