@enfyra/sdk-nuxt 0.2.0 → 0.2.1

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,15 +137,19 @@ 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)
+- `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)
@@ -228,10 +227,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 +246,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 +259,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 +291,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 +360,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 } = opts;
   if (ssr) {
     const config = useRuntimeConfig().public.enfyraSDK;
     const basePath = (typeof path === "function" ? path() : path).replace(/^\/?api\/?/, "").replace(/^\/+/, "");
@@ -127,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,12 +3,19 @@ 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 */
@@ -32,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;
@@ -44,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;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.1",
   "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.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,56 +1,52 @@
 import { ref, unref, toRaw } from "vue";
 import type {
   ApiOptions,
+  ApiError,
   BackendErrorExtended,
-  UseEnfyraApiReturn,
+  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 } = opts;
 
   // SSR mode - use useFetch
   if (ssr) {
@@ -99,10 +95,10 @@ 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?: {
@@ -195,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;
@@ -204,9 +200,9 @@ export function useEnfyraApi<T = any>(
   };
 
   return {
-    data: data as any,
+    data,
     error,
     pending,
     execute,
-  };
+  } as UseEnfyraApiClientReturn<T>;
 }

package/src/types/index.ts

@@ -4,12 +4,20 @@ 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 */
@@ -36,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;
@@ -49,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>