@forgepack/request 1.0.5 → 1.0.6

package/dist/index.js

@@ -1,16 +1,90 @@
 "use strict";
 /**
- * @fileoverview Pacote React para gerenciamento de requisições HTTP com autenticação JWT
- * @author Marcelo Gadelha
- * @version 1.0.3
+ * @forgepack/request - Complete HTTP client with JWT authentication for React
+ *
+ * @packageDocumentation
+ * @module @forgepack/request
+ *
+ * @description
+ * Production-ready solution for HTTP requests and JWT authentication in React applications
+ *
+ * @example
+ * **Quick Start**
+ * ```typescript
+ * import { createApiClient, AuthProvider, useAuth, useRequest } from '@forgepack/request'
+ *
+ * // 1. Create API client
+ * const api = createApiClient({
+ *   baseURL: 'https://api.example.com',
+ *   onUnauthorized: () => window.location.href = '/login'
+ * })
+ *
+ * // 2. Wrap app with AuthProvider
+ * function App() {
+ *   return (
+ *     <AuthProvider api={api}>
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </AuthProvider>
+ *   )
+ * }
+ *
+ * // 3. Use authentication
+ * function LoginPage() {
+ *   const { loginUser } = useAuth()
+ *
+ *   const handleLogin = async (credentials) => {
+ *     const result = await loginUser(credentials)
+ *     if (result.success) {
+ *       navigate('/dashboard')
+ *     }
+ *   }
+ *
+ *   return <LoginForm onSubmit={handleLogin} />
+ * }
+ *
+ * // 4. Fetch data with hooks
+ * function UsersPage() {
+ *   const { response, loading, error } = useRequest(
+ *     api,
+ *     'users',
+ *     { page: 0, size: 10 }
+ *   )
+ *
+ *   if (loading) return <Spinner />
+ *   if (error[0]?.message) return <Error message={error[0].message} />
+ *
+ *   return <UserList users={response.content} />
+ * }
+ *
+ * // 5. Protect routes
+ * <Route path="/admin" element={<RequireAuth allowedRoles={['ADMIN']} />}>
+ *   <Route index element={<AdminDashboard />} />
+ * </Route>
+ * ```
+ *
+ * @see {@link https://forgepack.dev/packages/request | Complete Documentation}
+ * @see {@link https://github.com/forgepack/request | GitHub Repository}
+ * @see {@link https://www.npmjs.com/package/@forgepack/request | NPM Package}
+ *
+ * @fileoverview React package for managing HTTP requests with JWT authentication
+ * @author Marcelo Gadelha {@link https://github.com/gadelhati}
+ * @version 1.0.6
  * @license Apache License 2.0
  *
- * Este pacote fornece uma solução completa para:
- * - Autenticação JWT com interceptors automáticos
- * - Hooks React para requisições e gerenciamento de estado
- * - Componentes de autenticação e autorização
- * - Operações CRUD padronizadas
- * - Gerenciamento de tokens e paginação
+ * @remarks
+ * This package requires React 16.8+ (hooks support) and axios as peer dependencies
+ *
+ * Complete solution for JWT authentication in React applications:
+ * - Automatic JWT authentication with Axios interceptors
+ * - React hooks for requests and state management (useAuth, useRequest)
+ * - Authentication and authorization components (AuthProvider, RequireAuth)
+ * - Standardized CRUD operations with error handling
+ * - Token management with automatic expiration checks
+ * - Pagination and search support for API requests
+ * - Request cancellation via AbortController
+ * - TypeScript support with comprehensive type definitions
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -27,23 +101,94 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// API client e configurações
+/**
+ * API client creation and configuration utilities
+ *
+ * @example
+ * ```typescript
+ * import { createApiClient } from '@forgepack/request'
+ *
+ * const api = createApiClient({
+ *   baseURL: process.env.REACT_APP_API_URL,
+ *   onUnauthorized: () => navigate('/login'),
+ *   onForbidden: () => toast.error('Access denied')
+ * })
+ * ```
+ */
 __exportStar(require("./api/client"), exports);
-// Tipos e interfaces
+/**
+ * Type definitions for authentication, errors, requests, responses and tokens
+ *
+ * @example
+ * ```typescript
+ * import type { Auth, LoginCredentials, ErrorMessage, Page } from '@forgepack/request'
+ *
+ * const credentials: LoginCredentials = {
+ *   username: 'user@example.com',
+ *   password: 'password123'
+ * }
+ * ```
+ */
 __exportStar(require("./types/auth"), exports);
 __exportStar(require("./types/error"), exports);
 __exportStar(require("./types/request"), exports);
 __exportStar(require("./types/response"), exports);
 __exportStar(require("./types/token"), exports);
-// Hooks React para gerenciamento de estado
+/**
+ * React hooks for authentication and request management
+ *
+ * @example
+ * ```typescript
+ * import { AuthProvider, useAuth, useRequest } from '@forgepack/request'
+ *
+ * // Authentication hook
+ * const { isAuthenticated, loginUser, logoutUser, role } = useAuth()
+ *
+ * // Request hook with pagination
+ * const { response, loading, error, request } = useRequest(
+ *   api,
+ *   'posts',
+ *   { page: 0, size: 20, sort: { key: 'createdAt', order: 'desc' } }
+ * )
+ * ```
+ */
 __exportStar(require("./hooks/AuthContext"), exports);
 __exportStar(require("./hooks/AuthProvider"), exports);
 __exportStar(require("./hooks/useAuth"), exports);
 __exportStar(require("./hooks/useRequest"), exports);
-// Serviços para operações de dados
+/**
+ * Service layer for API operations, authentication, CRUD and token management
+ *
+ * @example
+ * ```typescript
+ * import { login, create, retrieve, update, remove, fetchPage } from '@forgepack/request'
+ *
+ * // Authentication
+ * const result = await login(api, '/auth/login', credentials)
+ *
+ * // CRUD operations
+ * const newUser = await create(api, 'users', userData)
+ * const users = await retrieve(api, 'users', { page: 0, size: 10 })
+ * const updated = await update(api, 'users', { id: 1, name: 'New Name' })
+ * await remove(api, 'users', '1')
+ *
+ * // Paginated fetch
+ * const page = await fetchPage(api, 'posts', { page: 0, size: 20 })
+ * ```
+ */
 __exportStar(require("./services/api"), exports);
 __exportStar(require("./services/auth"), exports);
 __exportStar(require("./services/crud"), exports);
 __exportStar(require("./services/token"), exports);
-// Utilitários e constantes
+/**
+ * Utility constants and default values
+ *
+ * @example
+ * ```typescript
+ * import { initialAuth, initialPage, initialErrorMessage } from '@forgepack/request'
+ *
+ * const [auth, setAuth] = useState(initialAuth)
+ * const [page, setPage] = useState(initialPage)
+ * ```
+ */
 __exportStar(require("./utils/constants"), exports);

package/dist/services/api.d.ts

@@ -2,32 +2,54 @@ import { AxiosInstance } from 'axios';
 import { Page } from '../types/response';
 import { Search } from '../types/request';
 /**
- * Executa requisição paginada para um endpoint específico
+ * Executes a paginated GET request to a specific API endpoint with optional search and sorting
  *
- * Funcionalidades:
- * - Constrói URL com parâmetros de busca
- * - Adiciona parâmetros de paginação
- * - Suporte a ordenação
- * - Cancelamento de requisição via AbortSignal
+ * Features:
+ * - Builds URL with search parameters
+ * - Adds pagination parameters (page, size)
+ * - Supports sorting by field and order (asc/desc)
+ * - Request cancellation via AbortSignal
+ * - Automatic URL encoding for search values
  *
- * @param api - Instância configurada do Axios
- * @param endpoint - Endpoint da API (sem barra inicial)
- * @param search - Parâmetros opcionais de busca e paginação
- * @param signal - Signal para cancelamento da requisição
- * @returns Promise com dados paginados
+ * @param {AxiosInstance} api - Configured Axios instance with authentication and base URL
+ * @param {string} endpoint - API endpoint path (without leading slash, e.g., 'users' or 'posts')
+ * @param {Search} [search] - Optional search, pagination and sorting parameters
+ * @param {number} [search.page] - Page number (zero-indexed, default handled by backend)
+ * @param {number} [search.size] - Number of items per page (default handled by backend)
+ * @param {string} [search.value] - Search term for filtering results (URL encoded automatically)
+ * @param {Object} [search.sort] - Sorting configuration
+ * @param {string} [search.sort.key] - Field name to sort by (e.g., 'name', 'createdAt')
+ * @param {'asc'|'desc'} [search.sort.order] - Sort order (ascending or descending)
+ * @param {AbortSignal} [signal] - Signal for request cancellation (from AbortController)
+ * @returns {Promise<Page>} Promise resolving to paginated response data
  *
- * @throws {Error} Lança erro se a requisição falhar
+ * @throws {AxiosError} When the HTTP request fails
+ * @throws {Error} When request is aborted via signal
  *
  * @example
  * ```typescript
- * const controller = new AbortController()
- * const result = await fetchPage(
+ * // Most basic usage
+ * const result = await fetchPage(api, 'articles')
+ *
+ * // With sorting
+ * const promise = fetchPage(
  *   api,
  *   'users',
+ *   { page: 0, size: 10, sort: { key: 'createdAt', order: 'desc' } },
+ *   controller.signal
+ * )
+ *
+ * // With cancellation support
+ * const controller = new AbortController()
+ * const promise = fetchPage(
+ *   api,
+ *   'posts',
  *   { page: 0, size: 10, value: 'search term' },
  *   controller.signal
  * )
+ * // Cancel if needed
+ * controller.abort()
  * ```
  */
-export declare const fetchPage: (api: AxiosInstance, endpoint: string, search?: Search, signal?: AbortSignal) => Promise<Page>;
+export declare const fetchPage: <T>(api: AxiosInstance, endpoint: string, search?: Search, signal?: AbortSignal) => Promise<Page<T>>;
 //# sourceMappingURL=api.d.ts.map

package/dist/services/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/services/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,SAAS,GAAU,KAAK,aAAa,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CAkBzH,CAAA"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/services/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,EAAG,KAAK,aAAa,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAqBhI,CAAA"}

package/dist/services/api.js

@@ -2,45 +2,71 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchPage = void 0;
 /**
- * Executa requisição paginada para um endpoint específico
+ * Executes a paginated GET request to a specific API endpoint with optional search and sorting
  *
- * Funcionalidades:
- * - Constrói URL com parâmetros de busca
- * - Adiciona parâmetros de paginação
- * - Suporte a ordenação
- * - Cancelamento de requisição via AbortSignal
+ * Features:
+ * - Builds URL with search parameters
+ * - Adds pagination parameters (page, size)
+ * - Supports sorting by field and order (asc/desc)
+ * - Request cancellation via AbortSignal
+ * - Automatic URL encoding for search values
  *
- * @param api - Instância configurada do Axios
- * @param endpoint - Endpoint da API (sem barra inicial)
- * @param search - Parâmetros opcionais de busca e paginação
- * @param signal - Signal para cancelamento da requisição
- * @returns Promise com dados paginados
+ * @param {AxiosInstance} api - Configured Axios instance with authentication and base URL
+ * @param {string} endpoint - API endpoint path (without leading slash, e.g., 'users' or 'posts')
+ * @param {Search} [search] - Optional search, pagination and sorting parameters
+ * @param {number} [search.page] - Page number (zero-indexed, default handled by backend)
+ * @param {number} [search.size] - Number of items per page (default handled by backend)
+ * @param {string} [search.value] - Search term for filtering results (URL encoded automatically)
+ * @param {Object} [search.sort] - Sorting configuration
+ * @param {string} [search.sort.key] - Field name to sort by (e.g., 'name', 'createdAt')
+ * @param {'asc'|'desc'} [search.sort.order] - Sort order (ascending or descending)
+ * @param {AbortSignal} [signal] - Signal for request cancellation (from AbortController)
+ * @returns {Promise<Page>} Promise resolving to paginated response data
  *
- * @throws {Error} Lança erro se a requisição falhar
+ * @throws {AxiosError} When the HTTP request fails
+ * @throws {Error} When request is aborted via signal
  *
  * @example
  * ```typescript
- * const controller = new AbortController()
- * const result = await fetchPage(
+ * // Most basic usage
+ * const result = await fetchPage(api, 'articles')
+ *
+ * // With sorting
+ * const promise = fetchPage(
  *   api,
  *   'users',
+ *   { page: 0, size: 10, sort: { key: 'createdAt', order: 'desc' } },
+ *   controller.signal
+ * )
+ *
+ * // With cancellation support
+ * const controller = new AbortController()
+ * const promise = fetchPage(
+ *   api,
+ *   'posts',
  *   { page: 0, size: 10, value: 'search term' },
  *   controller.signal
  * )
+ * // Cancel if needed
+ * controller.abort()
  * ```
  */
 const fetchPage = async (api, endpoint, search, signal) => {
     var _a, _b, _c;
+    /** Build base URI with optional search query */
     const uri = ((_a = search === null || search === void 0 ? void 0 : search.value) === null || _a === void 0 ? void 0 : _a.trim())
         ? `/${endpoint}?value=${encodeURIComponent(search.value)}`
         : `/${endpoint}`;
+    /** Build request parameters */
     const params = {
         page: search === null || search === void 0 ? void 0 : search.page,
         size: search === null || search === void 0 ? void 0 : search.size
     };
+    /** Add sorting parameter if provided */
     if (((_b = search === null || search === void 0 ? void 0 : search.sort) === null || _b === void 0 ? void 0 : _b.order) && ((_c = search === null || search === void 0 ? void 0 : search.sort) === null || _c === void 0 ? void 0 : _c.key)) {
         params.sort = `${search.sort.key},${search.sort.order}`;
     }
+    /** Execute GET request with parameters and cancellation signal */
     const { data } = await api.get(uri, {
         params: Object.keys(params).length > 0 ? params : undefined,
         signal

package/dist/services/auth.d.ts

@@ -2,47 +2,104 @@ import { AxiosInstance } from 'axios';
 import { ErrorMessage } from '../types/error';
 import { LoginCredentials, LoginResponse, ChangePasswordData, ResetPasswordData } from '../types/auth';
 /**
- * Realiza login do usuário e armazena o token retornado
+ * Performs user login and stores the returned token
  *
- * @param api - Instância do Axios configurada
- * @param url - Endpoint de login
- * @param credentials - Credenciais do usuário
- * @returns Promise com resposta de login formatada
+ * @param {AxiosInstance} api - Configured Axios instance with base URL
+ * @param {string} url - Login endpoint path (e.g., '/auth/login')
+ * @param {LoginCredentials} credentials - User login credentials
+ * @param {string} credentials.username - Username or email
+ * @param {string} credentials.password - User password
+ * @returns {Promise<LoginResponse>} Promise resolving to login response with success flag and data/errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned in response
  *
  * @example
  * ```typescript
+ * // Successful login
  * const result = await login(api, '/auth/login', {
- *   username: 'user',
- *   password: 'pass'
+ *   username: 'john@snow.com',
+ *   password: 'SecurePass123!'
  * })
  *
  * if (result.success) {
- *   console.log('Logado!', result.data)
+ *   // Navigate to dashboard
+ *   console.log('Logged in!', result.data)
  * } else {
- *   console.error('Erros:', result.errors)
+ *   // Display errors to user
+ *   result.errors?.forEach(error => {
+ *     console.log(`${error.field}: ${error.message}`)
+ *   })
  * }
  * ```
  */
 export declare const login: (api: AxiosInstance, url: string, credentials: LoginCredentials) => Promise<LoginResponse>;
 /**
- * Realiza reset de senha do usuário e atualiza o token
+ * Performs password reset using a reset token and updates authentication
+ *
+ * @param {AxiosInstance} api - Configured Axios instance
+ * @param {string} url - Password reset endpoint path (e.g., '/auth/reset-password')
+ * @param {ResetPasswordData} data - Password reset data
+ * @param {string} data.token - Password reset token (from email)
+ * @param {string} data.newPassword - New password to set
+ * @returns {Promise<LoginResponse>} Promise with auth data on success or errors on failure
+ *
+ * @throws {never} Never throws - all errors are caught and returned in response
  *
- * @param api - Instância do Axios configurada
- * @param url - Endpoint de reset de senha
- * @param data - Dados para reset da senha
- * @returns Promise com dados de auth ou array de erros
+ * @example
+ * ```typescript
+ * ```
  */
 export declare const reset: (api: AxiosInstance, url: string, data: ResetPasswordData) => Promise<LoginResponse>;
 /**
- * Remove o token do localStorage e desloga o usuário
+ * Logs out the current user by removing authentication data from localStorage
+ *
+ * This function only clears local storage. For complete logout:
+ * - Call this function to clear local data
+ * - Redirect user to login page
+ *
+ * @returns {void}
+ *
+ * @example
+ * ```typescript
+ * logout()
+ * window.location.href = '/login'
+ * ```
  */
 export declare const logout: () => void;
 /**
- * Altera a senha do usuário autenticado
+ * Changes the password for an authenticated user
+ *
+ * Requires user to be authenticated (valid token in localStorage).
+ * User must provide current password for verification.
+ *
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {ChangePasswordData} data - Password change data
+ * @param {string} data.currentPassword - Current password for verification
+ * @param {string} data.newPassword - New password to set
+ * @param {string} data.confirmPassword - Confirm password to set
+ * @returns {Promise<{success: boolean; errors?: ErrorMessage[]}>} Promise with success status and optional errors
  *
- * @param api - Instância do Axios configurada
- * @param data - Dados para alteração da senha
- * @returns Promise com resposta de sucesso ou erros
+ * @throws {never} Never throws - all errors are caught and returned in response
+ *
+ * @example
+ * ```typescript
+ * // Password change in user settings
+ * const result = await changePassword(api, {
+ *   currentPassword: 'OldPass123!',
+ *   newPassword: 'NewSecurePass456!',
+ *   confirmPassword: 'NewSecurePass456!'
+ * })
+ * if (result.success) {
+ *   alert('Password changed successfully')
+ * } else {
+ *   // Display errors
+ *   result.errors?.forEach(err => {
+ *     if (err.field === 'currentPassword') {
+ *       console.error('Current password is incorrect')
+ *     }
+ *   })
+ * }
+ * ```
  */
 export declare const changePassword: (api: AxiosInstance, data: ChangePasswordData) => Promise<{
     success: boolean;

package/dist/services/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/services/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAQ,gBAAgB,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAwB5G;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,KAAK,GAAU,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,aAAa,gBAAgB,KAAG,OAAO,CAAC,aAAa,CAcjH,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAAU,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,iBAAiB,KAAG,OAAO,CAAC,aAAa,CAc3G,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,YAElB,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAU,KAAK,aAAa,EAAE,MAAM,kBAAkB,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,CAUxI,CAAA"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/services/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAQ,gBAAgB,EAAE,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAuC5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,KAAK,GAAU,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,aAAa,gBAAgB,KAAG,OAAO,CAAC,aAAa,CAcjH,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK,GAAU,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,iBAAiB,KAAG,OAAO,CAAC,aAAa,CAc3G,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,YAElB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,cAAc,GAAU,KAAK,aAAa,EAAE,MAAM,kBAAkB,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CAAE,CAUxI,CAAA"}

package/dist/services/auth.js

@@ -3,20 +3,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.changePassword = exports.logout = exports.reset = exports.login = void 0;
 const token_1 = require("./token");
 /**
- * Processa erros de resposta da API e converte em formato padronizado
+ * Processes API response errors and converts them to standardized format
  *
- * @param error - Objeto de erro do Axios
- * @returns Array de mensagens de erro formatadas
+ * @param {any} error - Axios error object
+ * @returns {ErrorMessage[]} Array of formatted error messages with field and message properties
+ *
+ * @internal This is a utility function used internally by auth service methods
+ *
+ * @example
+ * ```typescript
+ * // Validation errors response
+ * {
+ *   validationErrors: [
+ *     { field: 'email', message: 'Invalid email format' },
+ *     { field: 'password', message: 'Password too short' }
+ *   ]
+ * }
+ * ```
  */
 const addError = (error) => {
     var _a, _b, _c, _d;
     let errorMessage = [];
+    /** Check for validation errors in the response */
     if ((_b = (_a = error.response) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.validationErrors) {
         error.response.data.validationErrors.forEach((element) => {
             errorMessage.push({ field: element.field, message: element.message });
         });
     }
     else {
+        /** General errors */
         errorMessage.push({
             field: 'Error',
             message: ((_d = (_c = error.response) === null || _c === void 0 ? void 0 : _c.data) === null || _d === void 0 ? void 0 : _d.message) || 'Internal Error'
@@ -25,24 +40,33 @@ const addError = (error) => {
     return errorMessage;
 };
 /**
- * Realiza login do usuário e armazena o token retornado
+ * Performs user login and stores the returned token
+ *
+ * @param {AxiosInstance} api - Configured Axios instance with base URL
+ * @param {string} url - Login endpoint path (e.g., '/auth/login')
+ * @param {LoginCredentials} credentials - User login credentials
+ * @param {string} credentials.username - Username or email
+ * @param {string} credentials.password - User password
+ * @returns {Promise<LoginResponse>} Promise resolving to login response with success flag and data/errors
  *
- * @param api - Instância do Axios configurada
- * @param url - Endpoint de login
- * @param credentials - Credenciais do usuário
- * @returns Promise com resposta de login formatada
+ * @throws {never} Never throws - all errors are caught and returned in response
  *
  * @example
  * ```typescript
+ * // Successful login
  * const result = await login(api, '/auth/login', {
- *   username: 'user',
- *   password: 'pass'
+ *   username: 'john@snow.com',
+ *   password: 'SecurePass123!'
  * })
  *
  * if (result.success) {
- *   console.log('Logado!', result.data)
+ *   // Navigate to dashboard
+ *   console.log('Logged in!', result.data)
  * } else {
- *   console.error('Erros:', result.errors)
+ *   // Display errors to user
+ *   result.errors?.forEach(error => {
+ *     console.log(`${error.field}: ${error.message}`)
+ *   })
  * }
  * ```
  */
@@ -64,12 +88,20 @@ const login = async (api, url, credentials) => {
 };
 exports.login = login;
 /**
- * Realiza reset de senha do usuário e atualiza o token
+ * Performs password reset using a reset token and updates authentication
  *
- * @param api - Instância do Axios configurada
- * @param url - Endpoint de reset de senha
- * @param data - Dados para reset da senha
- * @returns Promise com dados de auth ou array de erros
+ * @param {AxiosInstance} api - Configured Axios instance
+ * @param {string} url - Password reset endpoint path (e.g., '/auth/reset-password')
+ * @param {ResetPasswordData} data - Password reset data
+ * @param {string} data.token - Password reset token (from email)
+ * @param {string} data.newPassword - New password to set
+ * @returns {Promise<LoginResponse>} Promise with auth data on success or errors on failure
+ *
+ * @throws {never} Never throws - all errors are caught and returned in response
+ *
+ * @example
+ * ```typescript
+ * ```
  */
 const reset = async (api, url, data) => {
     try {
@@ -89,18 +121,58 @@ const reset = async (api, url, data) => {
 };
 exports.reset = reset;
 /**
- * Remove o token do localStorage e desloga o usuário
+ * Logs out the current user by removing authentication data from localStorage
+ *
+ * This function only clears local storage. For complete logout:
+ * - Call this function to clear local data
+ * - Redirect user to login page
+ *
+ * @returns {void}
+ *
+ * @example
+ * ```typescript
+ * logout()
+ * window.location.href = '/login'
+ * ```
  */
 const logout = () => {
     (0, token_1.removeToken)();
 };
 exports.logout = logout;
 /**
- * Altera a senha do usuário autenticado
+ * Changes the password for an authenticated user
+ *
+ * Requires user to be authenticated (valid token in localStorage).
+ * User must provide current password for verification.
+ *
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {ChangePasswordData} data - Password change data
+ * @param {string} data.currentPassword - Current password for verification
+ * @param {string} data.newPassword - New password to set
+ * @param {string} data.confirmPassword - Confirm password to set
+ * @returns {Promise<{success: boolean; errors?: ErrorMessage[]}>} Promise with success status and optional errors
+ *
+ * @throws {never} Never throws - all errors are caught and returned in response
  *
- * @param api - Instância do Axios configurada
- * @param data - Dados para alteração da senha
- * @returns Promise com resposta de sucesso ou erros
+ * @example
+ * ```typescript
+ * // Password change in user settings
+ * const result = await changePassword(api, {
+ *   currentPassword: 'OldPass123!',
+ *   newPassword: 'NewSecurePass456!',
+ *   confirmPassword: 'NewSecurePass456!'
+ * })
+ * if (result.success) {
+ *   alert('Password changed successfully')
+ * } else {
+ *   // Display errors
+ *   result.errors?.forEach(err => {
+ *     if (err.field === 'currentPassword') {
+ *       console.error('Current password is incorrect')
+ *     }
+ *   })
+ * }
+ * ```
  */
 const changePassword = async (api, data) => {
     try {