@forgepack/request 1.0.4 → 1.0.6

package/dist/hooks/useAuth.d.ts

@@ -1,33 +1,54 @@
 import { AuthContextType } from './AuthContext';
 /**
- * Hook para acessar o contexto de autenticação
+ * Hook to access authentication context
  *
- * @returns Contexto de autenticação com estado e métodos
+ * @returns {AuthContextType} Authentication context with state and methods
+ * @throws {Error} If used outside of AuthProvider
  *
  * @example
  * ```typescript
- * const { isAuthenticated, loginUser, logoutUser, role } = useAuth()
+ * function ProfilePage() {
+ *   const { isAuthenticated, loginUser, logoutUser, role } = useAuth()
+ *   if (!isAuthenticated) {
+ *     return <p>Not authenticated</p>
+ *   }
+ *   return <div>User profile</div>
+ * }
  * ```
  */
 export declare const useAuth: () => AuthContextType;
 /**
- * Componente de proteção de rotas que verifica autenticação e autorização
+ * Properties of the RequireAuth component
+ */
+export type RequireAuthProps = {
+    /** Array of roles allowed to access the route */
+    allowedRoles: string[];
+};
+/**
+ * Route protection component that verifies authentication and authorization based on roles
  *
- * Comportamento:
- * - Se usuário tem role permitida: renderiza conteúdo (Outlet)
- * - Se autenticado mas sem permissão: redireciona para /notAllowed
- * - Se não autenticado: redireciona para /login
+ * Behavior:
+ * - If user has allowed role: renders content (Outlet)
+ * - If authenticated but without permission: redirects to /notAllowed
+ * - If not authenticated: redirects to /login
  *
- * @param props - Propriedades do componente
- * @param props.allowedRoles - Array de roles que têm acesso à rota
- * @returns Componente de navegação condicional
+ * @param {RequireAuthProps} props - Component properties
+ * @param {string[]} props.allowedRoles - Array of roles that have access to the route
+ * @returns {JSX.Element} Conditional navigation component
  *
  * @example
  * ```tsx
+ * // Protecting admin route
  * <Route path="/admin" element={<RequireAuth allowedRoles={['ADMIN']} />}>
  *   <Route index element={<AdminDashboard />} />
+ *   <Route path="users" element={<UserManagement />} />
+ * </Route>
+ *
+ * // Multiple roles
+ * <Route path="/moderator" element={<RequireAuth allowedRoles={['ADMIN', 'MODERATOR']} />}>
+ *   <Route index element={<ModeratorPanel />} />
  * </Route>
  * ```
  */
-export declare const RequireAuth: ({ allowedRoles }: any) => import("react/jsx-runtime").JSX.Element;
+export declare const RequireAuth: ({ allowedRoles }: RequireAuthProps) => import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=useAuth.d.ts.map

package/dist/hooks/useAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useAuth.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAe,eAAe,EAAE,MAAM,eAAe,CAAA;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO,QAAO,eAE1B,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GAAI,kBAAkB,GAAG,4CAWhD,CAAA"}
+{"version":3,"file":"useAuth.d.ts","sourceRoot":"","sources":["../../src/hooks/useAuth.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAe,eAAe,EAAE,MAAM,eAAe,CAAA;AAE5D;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,OAAO,QAAO,eAM1B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC3B,iDAAiD;IACjD,YAAY,EAAE,MAAM,EAAE,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,eAAO,MAAM,WAAW,GAAI,kBAAkB,gBAAgB,4CAW7D,CAAA"}

package/dist/hooks/useAuth.js

@@ -6,35 +6,53 @@ const react_1 = require("react");
 const react_router_dom_1 = require("react-router-dom");
 const AuthContext_1 = require("./AuthContext");
 /**
- * Hook para acessar o contexto de autenticação
+ * Hook to access authentication context
  *
- * @returns Contexto de autenticação com estado e métodos
+ * @returns {AuthContextType} Authentication context with state and methods
+ * @throws {Error} If used outside of AuthProvider
  *
  * @example
  * ```typescript
- * const { isAuthenticated, loginUser, logoutUser, role } = useAuth()
+ * function ProfilePage() {
+ *   const { isAuthenticated, loginUser, logoutUser, role } = useAuth()
+ *   if (!isAuthenticated) {
+ *     return <p>Not authenticated</p>
+ *   }
+ *   return <div>User profile</div>
+ * }
  * ```
  */
 const useAuth = () => {
-    return (0, react_1.useContext)(AuthContext_1.AuthContext);
+    const context = (0, react_1.useContext)(AuthContext_1.AuthContext);
+    if (!context) {
+        throw new Error('useAuth must be used within an AuthProvider');
+    }
+    return context;
 };
 exports.useAuth = useAuth;
 /**
- * Componente de proteção de rotas que verifica autenticação e autorização
+ * Route protection component that verifies authentication and authorization based on roles
  *
- * Comportamento:
- * - Se usuário tem role permitida: renderiza conteúdo (Outlet)
- * - Se autenticado mas sem permissão: redireciona para /notAllowed
- * - Se não autenticado: redireciona para /login
+ * Behavior:
+ * - If user has allowed role: renders content (Outlet)
+ * - If authenticated but without permission: redirects to /notAllowed
+ * - If not authenticated: redirects to /login
  *
- * @param props - Propriedades do componente
- * @param props.allowedRoles - Array de roles que têm acesso à rota
- * @returns Componente de navegação condicional
+ * @param {RequireAuthProps} props - Component properties
+ * @param {string[]} props.allowedRoles - Array of roles that have access to the route
+ * @returns {JSX.Element} Conditional navigation component
  *
  * @example
  * ```tsx
+ * // Protecting admin route
  * <Route path="/admin" element={<RequireAuth allowedRoles={['ADMIN']} />}>
  *   <Route index element={<AdminDashboard />} />
+ *   <Route path="users" element={<UserManagement />} />
+ * </Route>
+ *
+ * // Multiple roles
+ * <Route path="/moderator" element={<RequireAuth allowedRoles={['ADMIN', 'MODERATOR']} />}>
+ *   <Route index element={<ModeratorPanel />} />
  * </Route>
  * ```
  */

package/dist/hooks/useRequest.d.ts

@@ -3,35 +3,55 @@ import { Page } from '../types/response';
 import { Search } from '../types/request';
 import { AxiosInstance } from 'axios';
 /**
- * Hook React para gerenciamento de requisições HTTP paginadas com estado
+ * Return type of the useRequest hook
+ */
+export type UseRequestReturn = {
+    /** Paginated response data from the API */
+    response: Page;
+    /** Array of error messages if request failed */
+    error: ErrorMessage[];
+    /** Loading state indicator */
+    loading: boolean;
+    /** Function to manually trigger a new request */
+    request: () => Promise<void>;
+};
+/**
+ * React hook for managing paginated HTTP requests with automatic state management
  *
- * Funcionalidades:
- * - Gerencia estado de loading, dados e erros
- * - Suporte a paginação e busca
- * - Cancelamento automático de requisições pendentes
- * - Re-execução automática quando parâmetros mudam
+ * Features:
+ * - Manages loading, data and error states automatically
+ * - Supports pagination and search/filtering
+ * - Automatic cancellation of pending requests on unmount or parameter change
+ * - Automatic re-execution when endpoint or search parameters change
+ * - Request deduplication via AbortController
  *
- * @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
- * @returns Objeto contendo response, error, loading e função request
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} endpoint - API endpoint path (without leading slash, e.g., 'users' or 'posts')
+ * @param {Search} [search] - Optional search and pagination parameters
+ * @param {number} [search.page] - Page number (zero-indexed)
+ * @param {number} [search.size] - Number of items per page
+ * @param {string} [search.value] - Search term for filtering results
+ * @returns {UseRequestReturn} Object containing response data, error state, loading indicator and manual request function
  *
  * @example
  * ```typescript
+ * // Basic usage with pagination
  * const { response, error, loading, request } = useRequest(
  *   apiClient,
  *   'users',
+ *   { page: 0, size: 10 }
+ * )
+ *
+ * // Access paginated data
+ * const { response, loading } = useRequest(
+ *   apiClient,
+ *   'posts',
  *   { page: 0, size: 10, value: 'search term' }
  * )
  *
- * // Re-executar manualmente
+ * // Re-execute manually to refresh data
  * await request()
  * ```
  */
-export declare const useRequest: (api: AxiosInstance, endpoint: string, search?: Search) => {
-    response: Page<unknown>;
-    error: ErrorMessage[];
-    loading: boolean;
-    request: () => Promise<void>;
-};
+export declare const useRequest: (api: AxiosInstance, endpoint: string, search?: Search) => UseRequestReturn;
 //# sourceMappingURL=useRequest.d.ts.map

package/dist/hooks/useRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useRequest.d.ts","sourceRoot":"","sources":["../../src/hooks/useRequest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE7C,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,aAAa,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM;;;;;CA8B/E,CAAA"}
+{"version":3,"file":"useRequest.d.ts","sourceRoot":"","sources":["../../src/hooks/useRequest.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE7C,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAA;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAEzC,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAErC;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC3B,2CAA2C;IAC3C,QAAQ,EAAE,IAAI,CAAA;IACd,gDAAgD;IAChD,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,iDAAiD;IACjD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,eAAO,MAAM,UAAU,GAAI,KAAK,aAAa,EAAE,UAAU,MAAM,EAAE,SAAS,MAAM,KAAG,gBAyClF,CAAA"}

package/dist/hooks/useRequest.js

@@ -5,28 +5,40 @@ const react_1 = require("react");
 const constants_1 = require("../utils/constants");
 const api_1 = require("../services/api");
 /**
- * Hook React para gerenciamento de requisições HTTP paginadas com estado
+ * React hook for managing paginated HTTP requests with automatic state management
  *
- * Funcionalidades:
- * - Gerencia estado de loading, dados e erros
- * - Suporte a paginação e busca
- * - Cancelamento automático de requisições pendentes
- * - Re-execução automática quando parâmetros mudam
+ * Features:
+ * - Manages loading, data and error states automatically
+ * - Supports pagination and search/filtering
+ * - Automatic cancellation of pending requests on unmount or parameter change
+ * - Automatic re-execution when endpoint or search parameters change
+ * - Request deduplication via AbortController
  *
- * @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
- * @returns Objeto contendo response, error, loading e função request
+ * @param {AxiosInstance} api - Configured Axios instance with authentication
+ * @param {string} endpoint - API endpoint path (without leading slash, e.g., 'users' or 'posts')
+ * @param {Search} [search] - Optional search and pagination parameters
+ * @param {number} [search.page] - Page number (zero-indexed)
+ * @param {number} [search.size] - Number of items per page
+ * @param {string} [search.value] - Search term for filtering results
+ * @returns {UseRequestReturn} Object containing response data, error state, loading indicator and manual request function
  *
  * @example
  * ```typescript
+ * // Basic usage with pagination
  * const { response, error, loading, request } = useRequest(
  *   apiClient,
  *   'users',
+ *   { page: 0, size: 10 }
+ * )
+ *
+ * // Access paginated data
+ * const { response, loading } = useRequest(
+ *   apiClient,
+ *   'posts',
  *   { page: 0, size: 10, value: 'search term' }
  * )
  *
- * // Re-executar manualmente
+ * // Re-execute manually to refresh data
  * await request()
  * ```
  */
@@ -35,8 +47,14 @@ const useRequest = (api, endpoint, search) => {
     const [error, setError] = (0, react_1.useState)([constants_1.initialErrorMessage]);
     const [loading, setLoading] = (0, react_1.useState)(false);
     const abortControllerRef = (0, react_1.useRef)(null);
+    /**
+     * Executes the API request with automatic cancellation of previous pending requests
+     *
+     * @throws {ErrorMessage} When the request fails
+     */
     const request = (0, react_1.useCallback)(async () => {
         var _a;
+        /** Cancel any ongoing request */
         (_a = abortControllerRef.current) === null || _a === void 0 ? void 0 : _a.abort();
         const controller = new AbortController();
         abortControllerRef.current = controller;
@@ -47,15 +65,20 @@ const useRequest = (api, endpoint, search) => {
             setResponse(data);
         }
         catch (requestError) {
-            setError([requestError]);
+            /** Ignore abort errors */
+            if (requestError.name !== 'AbortError') {
+                setError([requestError]);
+            }
         }
         finally {
             setLoading(false);
             abortControllerRef.current = null;
         }
-    }, [endpoint, search]);
+    }, [api, endpoint, search]);
+    /** Automatically execute request on mount and when dependencies change */
     (0, react_1.useEffect)(() => {
         request();
+        /** Cleanup: cancel request on unmount or dependency change */
         return () => { var _a; return (_a = abortControllerRef.current) === null || _a === void 0 ? void 0 : _a.abort(); };
     }, [request]);
     return { response, error, loading, request };

package/dist/index.d.ts

@@ -1,29 +1,179 @@
 /**
- * @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
+ */
+/**
+ * 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')
+ * })
+ * ```
  */
 export * from './api/client';
+/**
+ * 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'
+ * }
+ * ```
+ */
 export * from './types/auth';
 export * from './types/error';
 export * from './types/request';
 export * from './types/response';
 export * from './types/token';
+/**
+ * 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' } }
+ * )
+ * ```
+ */
 export * from './hooks/AuthContext';
 export * from './hooks/AuthProvider';
 export * from './hooks/useAuth';
 export * from './hooks/useRequest';
+/**
+ * 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 })
+ * ```
+ */
 export * from './services/api';
 export * from './services/auth';
 export * from './services/crud';
 export * from './services/token';
+/**
+ * Utility constants and default values
+ *
+ * @example
+ * ```typescript
+ * import { initialAuth, initialPage, initialErrorMessage } from '@forgepack/request'
+ *
+ * const [auth, setAuth] = useState(initialAuth)
+ * const [page, setPage] = useState(initialPage)
+ * ```
+ */
 export * from './utils/constants';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,cAAc,cAAc,CAAA;AAG5B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAG7B,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAGlC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAGhC,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAEH;;;;;;;;;;;;;GAaG;AACH,cAAc,cAAc,CAAA;AAE5B;;;;;;;;;;;;GAYG;AACH,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,eAAe,CAAA;AAE7B;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAc,qBAAqB,CAAA;AACnC,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAEhC;;;;;;;;;;GAUG;AACH,cAAc,mBAAmB,CAAA"}