@arex95/vue-core 1.1.15 → 1.1.19

package/dist/composables/auth/useAuth.d.ts

@@ -1,17 +1,57 @@
 /**
- * Provides authentication utilities.
- *
- * @param {string} [secretKey=getSecretKey()] - Encryption key.
- * @returns {Object} Auth composable methods and properties.
+ * Converts an ArrayBuffer to a hexadecimal string.
+ * @param {Uint8Array} buffer - The Uint8Array to convert.
+ * @returns {string} The hexadecimal string representation.
+ */
+declare function ab2hex(buffer: Uint8Array): string;
+/**
+ * Converts a hexadecimal string to a Uint8Array.
+ * @param {string} hex - The hexadecimal string to convert.
+ * @returns {Uint8Array} The Uint8Array representation.
+ */
+declare function hex2ab(hex: string): Uint8Array;
+/**
+ * Imports a secret key for cryptographic operations.
+ * @param {string} secretKey - The string secret key.
+ * @returns {Promise<CryptoKey>} A Promise that resolves to the CryptoKey.
+ */
+declare function importKey(secretKey: string): Promise<CryptoKey>;
+/**
+ * Interface for the expected structure of a successful login response from the API.
+ */
+interface LoginResponse {
+    access_token: string;
+    refresh_token: string;
+    [key: string]: unknown;
+}
+/**
+ * Interface for the expected structure of a successful token refresh response from the API.
+ */
+interface RefreshResponse {
+    access_token: string;
+    refresh_token: string;
+    [key: string]: unknown;
+}
+/**
+ * A Vue composable that provides authentication utilities, enforcing asynchronous access to tokens.
+ * All token-related properties and status checks are awaitable functions.
+ * @param {string} [secretKey=getSecretKey()] - The encryption/decryption key. Defaults to a globally configured key.
+ * @returns {object} An object containing asynchronous authentication methods and properties.
  */
 export declare function useAuth(secretKey?: string): {
-    isAuthenticated: import("vue").ComputedRef<boolean>;
-    jwt: import("vue").Ref<string | null, string | null>;
-    refresh_token: import("vue").Ref<string | null, string | null>;
-    tokenExpiry: import("vue").ComputedRef<number | null>;
-    login: (params: {} | undefined, isRememberMe: boolean) => Promise<import("axios").AxiosResponse<any, any>>;
-    refresh: () => Promise<import("axios").AxiosResponse<any, any> | undefined>;
-    logout: (params?: {}) => Promise<void>;
+    getJwt: () => Promise<string | null>;
+    getRefreshToken: () => Promise<string | null>;
+    isAuthenticated: () => Promise<boolean>;
+    getTokenExpiry: () => Promise<number | null>;
+    login: (params: object | undefined, isRememberMe: boolean) => Promise<LoginResponse>;
+    refresh: () => Promise<RefreshResponse>;
+    logout: (params?: object) => Promise<void>;
     cleanStorage: () => Promise<void>;
     verifyToken: () => Promise<void>;
+    ab2hex: typeof ab2hex;
+    hex2ab: typeof hex2ab;
+    importKey: typeof importKey;
+    encrypt: (value: string, secretKey: string) => Promise<string>;
+    decrypt: (value: string, secretKey: string) => Promise<string>;
 };
+export {};

package/dist/composables/monitoring/useApiActivity.d.ts

@@ -1,4 +1,12 @@
-export declare function useApiActivity(sessionTimeoutMin: number, checkIntervalSec: number): {
+/**
+ * A Vue composable to monitor API activity and manage session timeouts.
+ * It tracks the last user activity and automatically logs out the user
+ * if no activity is detected within a specified timeout.
+ * @param {number} [sessionTimeoutMin=SESSION_TIMEOUT_MINUTES] - The time in minutes after which an inactive session will time out.
+ * @param {number} [checkIntervalSec=CHECK_INTERVAL_SECONDS] - The interval in seconds at which the session timeout is checked.
+ * @returns {object} An object containing methods to pause, resume, and manually update the activity timestamp.
+ */
+export declare function useApiActivity(sessionTimeoutMin?: number, checkIntervalSec?: number): {
     pause: import("@vueuse/core").Fn;
     resume: import("@vueuse/core").Fn;
     updateTimestamp: () => void;

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { useTimeoutFn, useBreakpoints, breakpointsTailwind, useWindowSize, computedAsync } from '@vueuse/core';
+import { useTimeoutFn, useBreakpoints, breakpointsTailwind, useWindowSize } from '@vueuse/core';
 import axios from 'axios';
 import { useRouter } from 'vue-router';
 import { useQuery } from '@tanstack/vue-query';
@@ -2989,14 +2989,33 @@ function useSorter(items, criteriaList, selectedCriteria) {
     }).value;
 }
 
+/**
+ * Converts an ArrayBuffer to a hexadecimal string.
+ * @param {Uint8Array} buffer - The Uint8Array to convert.
+ * @returns {string} The hexadecimal string representation.
+ */
 function ab2hex(buffer) {
     return Array.from(buffer)
         .map((b) => b.toString(16).padStart(2, "0"))
         .join("");
 }
+/**
+ * Converts a hexadecimal string to a Uint8Array.
+ * @param {string} hex - The hexadecimal string to convert.
+ * @returns {Uint8Array} The Uint8Array representation.
+ */
 function hex2ab(hex) {
-    return new Uint8Array(hex.match(/.{1,2}/g).map((byte) => parseInt(byte, 16)));
+    const matches = hex.match(/.{1,2}/g);
+    if (!matches) {
+        return new Uint8Array([]);
+    }
+    return new Uint8Array(matches.map((byte) => parseInt(byte, 16)));
 }
+/**
+ * Imports a secret key for cryptographic operations.
+ * @param {string} secretKey - The string secret key.
+ * @returns {Promise<CryptoKey>} A Promise that resolves to the CryptoKey.
+ */
 async function importKey(secretKey) {
     const encoder = new TextEncoder();
     const keyMaterial = await crypto.subtle.digest("SHA-256", encoder.encode(secretKey));
@@ -3005,7 +3024,6 @@ async function importKey(secretKey) {
 /**
  * Encrypts a value using AES-256 CBC encryption with Web Cryptography API.
  * The IV is generated randomly for each encryption and prepended to the ciphertext.
- *
  * @param {string} value - The value to encrypt.
  * @param {string} secretKey - The encryption key string.
  * @returns {Promise<string>} A promise that resolves to the encrypted string (hex IV + hex ciphertext).
@@ -3022,7 +3040,6 @@ const encrypt = async (value, secretKey) => {
 /**
  * Decrypts an AES-256 CBC encrypted value using Web Cryptography API.
  * The IV is extracted from the beginning of the encrypted string.
- *
  * @param {string} value - The encrypted string (hex IV + hex ciphertext).
  * @param {string} secretKey - The decryption key string.
  * @returns {Promise<string>} A promise that resolves to the decrypted string.
@@ -3036,13 +3053,13 @@ const decrypt = async (value, secretKey) => {
 };
 /**
  * Stores an encrypted value in sessionStorage or localStorage.
- *
  * @param {string} key - Storage key.
  * @param {string} value - Value to store.
  * @param {string} secretKey - Encryption key.
- * @param {boolean} isRememberMe - Whether to store in localStorage.
+ * @param {boolean} isRememberMe - Whether to store in localStorage (true) or sessionStorage (false).
  * @param {number} [attempt=0] - Retry attempt count.
- * @returns {Promise<void>}
+ * @returns {Promise<void>} A Promise that resolves when the item is stored.
+ * @throws {Error} If storage is not available after multiple attempts.
  */
 const storeEncryptedItem = async (key, value, secretKey, isRememberMe, attempt = 0) => {
     const storage = isRememberMe ? localStorage : sessionStorage;
@@ -3070,15 +3087,14 @@ const storeEncryptedItem = async (key, value, secretKey, isRememberMe, attempt =
     }
 };
 /**
- * Retrieves and decrypts a stored value.
- *
+ * Retrieves and decrypts a stored value from sessionStorage or localStorage.
  * @param {string} key - Storage key.
  * @param {string} secretKey - Decryption key.
- * @param {boolean} isRememberMe - Whether to retrieve from localStorage.
- * @returns {Promise<string|null>} The decrypted value or null.
+ * @param {boolean} isRememberMe - Whether to retrieve from localStorage (true) or sessionStorage (false).
+ * @returns {Promise<string|null>} The decrypted value or null if not found or decryption fails.
  */
 async function getDecryptedValue(key, secretKey, isRememberMe) {
-    const storage = sessionStorage;
+    const storage = isRememberMe ? localStorage : sessionStorage;
     try {
         const value = storage.getItem(key);
         if (!value)
@@ -3091,58 +3107,84 @@ async function getDecryptedValue(key, secretKey, isRememberMe) {
     }
 }
 /**
- * Provides authentication utilities.
- *
- * @param {string} [secretKey=getSecretKey()] - Encryption key.
- * @returns {Object} Auth composable methods and properties.
+ * A Vue composable that provides authentication utilities, enforcing asynchronous access to tokens.
+ * All token-related properties and status checks are awaitable functions.
+ * @param {string} [secretKey=getSecretKey()] - The encryption/decryption key. Defaults to a globally configured key.
+ * @returns {object} An object containing asynchronous authentication methods and properties.
  */
 function useAuth(secretKey = getSecretKey()) {
     const axiosInstance = getAxiosInstance();
     const tokensConfig = getTokenConfig();
     const endpointsConfig = getEndpointsConfig();
-    const config = {
+    const authConfig = {
         endpoints: endpointsConfig,
         storageKeys: tokensConfig,
     };
-    const jwt = computedAsync(async () => await getDecryptedValue(config.storageKeys.ACCESS_TOKEN, secretKey), null);
-    const refresh_token = computedAsync(async () => await getDecryptedValue(config.storageKeys.REFRESH_TOKEN, secretKey), null);
     /**
-     * Computes token expiration timestamp.
+     * Asynchronously retrieves and decrypts the Access Token (JWT) from storage.
+     * This function should always be awaited.
+     * @returns {Promise<string|null>} A promise that resolves to the decrypted JWT string or null if not found.
+     */
+    const getJwt = async () => {
+        return await getDecryptedValue(authConfig.storageKeys.ACCESS_TOKEN, secretKey, false);
+    };
+    /**
+     * Asynchronously retrieves and decrypts the Refresh Token from storage.
+     * This function should always be awaited.
+     * @returns {Promise<string|null>} A promise that resolves to the decrypted Refresh Token string or null if not found.
      */
-    const tokenExpiry = computed(() => {
-        if (!jwt.value)
+    const getRefreshToken = async () => {
+        return await getDecryptedValue(authConfig.storageKeys.REFRESH_TOKEN, secretKey, true);
+    };
+    /**
+     * Asynchronously computes the expiration timestamp of the current Access Token.
+     * Requires awaiting the JWT.
+     * @returns {Promise<number|null>} A promise that resolves to the expiration timestamp in milliseconds (Unix epoch) or null if no valid token is found or parsing fails.
+     */
+    const getTokenExpiry = async () => {
+        const token = await getJwt();
+        if (!token)
             return null;
         try {
-            const decoded = jwtDecode(jwt.value);
+            const decoded = jwtDecode(token);
             return decoded.exp ? decoded.exp * 1000 : null;
         }
         catch (error) {
             handleError(error, false);
             return null;
         }
-    });
+    };
     /**
-     * Checks if the user is authenticated.
+     * Asynchronously checks if the user is currently authenticated and if the Access Token is valid and not expired.
+     * This function should always be awaited.
+     * @returns {Promise<boolean>} A promise that resolves to true if authenticated and token is valid, false otherwise.
      */
-    const isAuthenticated = computed(() => {
-        if (!jwt.value || jwt.value.length === 0) {
+    const isAuthenticated = async () => {
+        const token = await getJwt();
+        if (!token || token.length === 0) {
             return false;
         }
-        if (tokenExpiry.value === null) {
+        const expiry = await getTokenExpiry();
+        if (expiry === null) {
             return false;
         }
-        return tokenExpiry.value > Date.now();
-    });
+        return expiry > Date.now();
+    };
     /**
-     * Handles user login.
+     * Handles user login by making an API request and storing the received tokens.
+     * @param {object} [params={}] - The login credentials or payload.
+     * @param {boolean} isRememberMe - Indicates whether the refresh token should be stored in localStorage.
+     * @returns {Promise<LoginResponse>} A promise that resolves to the API response data on successful login.
+     * @throws {Error} If the login request fails.
      */
     const login = async (params = {}, isRememberMe) => {
         try {
-            const response = await axiosInstance.post(config.endpoints.LOGIN, params);
-            await storeEncryptedItem(config.storageKeys.ACCESS_TOKEN, response.data.access_token, secretKey, isRememberMe);
-            await storeEncryptedItem(config.storageKeys.REFRESH_TOKEN, response.data.refresh_token, secretKey, isRememberMe);
-            await jwt.value;
-            return response;
+            const response = await axiosInstance.post(authConfig.endpoints.LOGIN, params);
+            const newAccessToken = response.data.access_token;
+            const newRefreshToken = response.data.refresh_token;
+            await storeEncryptedItem(authConfig.storageKeys.ACCESS_TOKEN, newAccessToken, secretKey, false);
+            await storeEncryptedItem(authConfig.storageKeys.REFRESH_TOKEN, newRefreshToken, secretKey, isRememberMe);
+            return response.data;
         }
         catch (error) {
             handleError(error, false);
@@ -3150,26 +3192,34 @@ function useAuth(secretKey = getSecretKey()) {
         }
     };
     /**
-     * Refreshes authentication token.
+     * Refreshes the authentication token by making an API request and updating stored tokens.
+     * @returns {Promise<RefreshResponse>} A promise that resolves to the API response data on successful refresh.
+     * @throws {Error} If the refresh request fails, leading to logout.
      */
     const refresh = async () => {
         try {
-            const response = await axiosInstance.post(config.endpoints.REFRESH, {});
-            await storeEncryptedItem(config.storageKeys.ACCESS_TOKEN, response.data.token, secretKey, false);
-            await storeEncryptedItem(config.storageKeys.REFRESH_TOKEN, response.data.refresh_token, secretKey, false);
-            return response;
+            const response = await axiosInstance.post(authConfig.endpoints.REFRESH, {});
+            const newAccessToken = response.data.access_token;
+            const newRefreshToken = response.data.refresh_token;
+            await storeEncryptedItem(authConfig.storageKeys.ACCESS_TOKEN, newAccessToken, secretKey, false);
+            await storeEncryptedItem(authConfig.storageKeys.REFRESH_TOKEN, newRefreshToken, secretKey, true);
+            return response.data;
         }
         catch (error) {
             handleError(error, false);
             await logout();
+            throw error;
         }
     };
     /**
-     * Logs out the user.
+     * Handles user logout by making an API request and clearing stored authentication data.
+     * Reloads the page after clearing storage.
+     * @param {object} [params={}] - Optional logout payload.
+     * @returns {Promise<void>} A promise that resolves when the logout process is complete.
      */
     const logout = async (params = {}) => {
         try {
-            await axiosInstance.post(config.endpoints.LOGOUT, params);
+            await axiosInstance.post(authConfig.endpoints.LOGOUT, params);
         }
         catch (error) {
             handleError(error, false);
@@ -3180,25 +3230,31 @@ function useAuth(secretKey = getSecretKey()) {
         }
     };
     /**
-     * Clears stored authentication data.
+     * Clears all stored authentication data (access and refresh tokens) from both sessionStorage and localStorage.
+     * @returns {Promise<void>} A promise that resolves when all relevant storage items are removed.
      */
     const cleanStorage = async () => {
-        Object.keys(config.storageKeys).forEach((key) => {
-            sessionStorage.removeItem(config.storageKeys[key]);
-            localStorage.removeItem(config.storageKeys[key]);
+        Object.keys(authConfig.storageKeys).forEach((key) => {
+            sessionStorage.removeItem(authConfig.storageKeys[key]);
+            localStorage.removeItem(authConfig.storageKeys[key]);
         });
     };
     /**
-     * Verifies token validity.
+     * Verifies the validity of the current Access Token. If the token is missing, invalid, or expired,
+     * it handles the error appropriately (e.g., attempts refresh, clears storage, redirects).
+     * This function should always be awaited.
+     * @returns {Promise<void>} A promise that resolves if the token is valid, or rejects with an error.
+     * @throws {Error} If the token is missing, expired, or invalid.
      */
     const verifyToken = async () => {
-        if (!jwt.value) {
+        const token = await getJwt();
+        if (!token) {
             handleError("TOKEN_MISSING: No valid token found", true, "/auth-error", "query");
             await cleanStorage();
             throw new Error("TOKEN_MISSING: No valid token found");
         }
         try {
-            const decoded = jwtDecode(jwt.value);
+            const decoded = jwtDecode(token);
             if (decoded.exp ? decoded.exp * 1000 < Date.now() : false) {
                 handleError("TOKEN_EXPIRED", false);
                 await refresh();
@@ -3215,15 +3271,20 @@ function useAuth(secretKey = getSecretKey()) {
         }
     };
     return {
+        getJwt,
+        getRefreshToken,
         isAuthenticated,
-        jwt,
-        refresh_token,
-        tokenExpiry,
+        getTokenExpiry,
         login,
         refresh,
         logout,
         cleanStorage,
         verifyToken,
+        ab2hex,
+        hex2ab,
+        importKey,
+        encrypt,
+        decrypt,
     };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arex95/vue-core",
-  "version": "1.1.15",
+  "version": "1.1.19",
   "description": "Opinionated Vue Core",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -15,7 +15,10 @@
   "scripts": {
     "build": "rollup -c",
     "changelog": "conventional-changelog -p angular -o CHANGELOG.md -r 0",
-    "release": "npm version patch && npm run changelog && git add CHANGELOG.md package.json package-lock.json && git commit -m \"chore(release): update changelog\" && git push && npm publish --access public"
+    "release": "npm version patch && npm run changelog && git add CHANGELOG.md package.json pnpm-lock.yaml && git commit -m \"chore(release): update changelog\" && git push && npm publish --access public",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:ui": "vitest --ui"
   },
   "repository": {
     "type": "git",
@@ -46,15 +49,19 @@
     "@rollup/plugin-typescript": "^12.1.2",
     "@types/crypto-js": "^4.2.2",
     "@types/node": "^22.13.10",
+    "@vitest/ui": "^3.2.3",
+    "@vue/test-utils": "^2.4.6",
     "conventional-changelog-cli": "^5.0.0",
     "eslint": "^9.23.0",
     "eslint-plugin-vue": "^10.0.0",
     "globals": "^16.0.0",
+    "jsdom": "^26.1.0",
     "rollup": "^4.35.0",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "typescript": "^5.8.2",
-    "typescript-eslint": "^8.28.0"
+    "typescript-eslint": "^8.28.0",
+    "vitest": "^3.2.3"
   },
   "dependencies": {
     "@tanstack/vue-query": ">=5.0.0",