@exyconn/common 2.3.2 → 2.3.4

package/README.md

@@ -78,10 +78,11 @@ import { successResponse, errorResponse } from '@exyconn/common/server/response'
 import { createCorsOptions, createRateLimiter } from '@exyconn/common/server/configs';
 import { createLogger } from '@exyconn/common/server/logger';
 import { connectDB } from '@exyconn/common/server/db';
+import { createCrudControllers, queryParser, queryPagination } from '@exyconn/common/server/middleware';
 
 // Client utilities
 import { useLocalStorage, useDebounce } from '@exyconn/common/client/hooks';
-import { createHttpClient } from '@exyconn/common/client/http';
+import { getRequest, postRequest, extractData, isSuccess } from '@exyconn/common/client/http';
 
 // Shared utilities
 import { isValidEmail, VALIDATION_PATTERNS } from '@exyconn/common/shared/validation';
@@ -491,6 +492,52 @@ await disconnectDB(logger);
 
 #### Middleware (`@exyconn/common/server/middleware`)
 
+##### CRUD Controller Factory
+
+```typescript
+import { createCrudControllers } from '@exyconn/common/server/middleware';
+import { z } from 'zod';
+import { User } from './models/User';
+
+const userController = createCrudControllers({
+  model: User,
+  resourceName: 'User',
+  createSchema: z.object({ name: z.string(), email: z.string().email() }),
+  updateSchema: z.object({ name: z.string().optional() }),
+  searchFields: ['name', 'email'],
+  withOrganization: true,
+});
+
+// Auto-generated routes
+router.get('/users', userController.getAll);
+router.get('/users/:id', userController.getById);
+router.post('/users', userController.create);
+router.put('/users/:id', userController.update);
+router.delete('/users/:id', userController.deleteOne);
+router.delete('/users', userController.bulkDelete);
+```
+
+##### Query Parser & Pagination
+
+```typescript
+import { queryParser, queryPagination } from '@exyconn/common/server/middleware';
+
+router.get('/users', queryParser, async (req, res) => {
+  const { page, limit, sort, search, filter } = req.parsedQuery;
+  // page: 1, limit: 10, sort: { createdAt: 'desc' }, search: 'john'
+  
+  await queryPagination(User, {
+    searchFields: ['name', 'email'],
+    populate: ['department'],
+  }, true)(req, res, () => {});
+  
+  res.json(res.paginatedResult);
+  // { data: [...], meta: { total, page, limit, totalPages }, columns: [...] }
+});
+```
+
+##### Authentication Middleware
+
 ```typescript
 import { 
   authenticateJWT,
@@ -498,7 +545,6 @@ import {
   authenticateApiKey,
   extractOrganization,
   type AuthRequest,
-  type JWTPayload,
 } from '@exyconn/common/server/middleware';
 
 // JWT Authentication (required)
@@ -642,18 +688,77 @@ const meta = buildPaginationMeta(totalCount, pagination.page, pagination.limit);
 #### HTTP Client (`@exyconn/common/client/http`)
 
 ```typescript
-import { createHttpClient, withFormData, withTimeout } from '@exyconn/common/client/http';
+import {
+  getRequest,
+  postRequest,
+  putRequest,
+  patchRequest,
+  deleteRequest,
+  uploadFile,
+  extractData,
+  extractPaginatedData,
+  isSuccess,
+  parseError,
+} from '@exyconn/common/client/http';
+
+// GET request
+const response = await getRequest('/api/users');
+const users = extractData(response);
+
+// POST request  
+const createResponse = await postRequest('/api/users', { name: 'John' });
+if (isSuccess(createResponse)) {
+  console.log('User created!');
+}
 
-const api = createHttpClient({
-  baseURL: 'https://api.example.com',
-  timeout: 30000,
-  getAuthToken: () => localStorage.getItem('token'),
-  onUnauthorized: () => window.location.href = '/login',
-});
+// Paginated response
+const paginatedResponse = await getRequest('/api/users', { page: 1, limit: 10 });
+const { items, total, page, totalPages } = extractPaginatedData(paginatedResponse);
+
+// File upload
+const uploadResponse = await uploadFile('/api/upload', file, { folder: 'avatars' });
+
+// Error handling
+try {
+  await postRequest('/api/users', invalidData);
+} catch (error) {
+  const { message, statusCode } = parseError(error);
+}
+```
+
+**HTTP Functions:**
+
+| Function | Parameters | Returns | Description |
+|----------|------------|---------|-------------|
+| `getRequest` | `url, params?, headers?` | `Promise<AxiosResponse>` | GET request |
+| `postRequest` | `url, data?, headers?` | `Promise<AxiosResponse>` | POST request |
+| `putRequest` | `url, data?, headers?` | `Promise<AxiosResponse>` | PUT request |
+| `patchRequest` | `url, data?, headers?` | `Promise<AxiosResponse>` | PATCH request |
+| `deleteRequest` | `url, params?, headers?` | `Promise<AxiosResponse>` | DELETE request |
+| `uploadFile` | `url, file, data?` | `Promise<AxiosResponse>` | File upload |
+
+**Response Utilities:**
+
+| Function | Description |
+|----------|-------------|
+| `extractData` | Extract data from axios response |
+| `extractMessage` | Extract message from response |
+| `extractPaginatedData` | Extract paginated data with meta |
+| `isSuccess` | Check if response status is 2xx |
+| `isSuccessResponse` | Check response data for success |
+| `parseError` | Parse error to standardized format |
+| `parseResponseData` | Parse data from raw response |
+| `parsePaginatedResponse` | Parse paginated response data |
+| `safeJsonParse` | Safe JSON parsing with fallback |
+
+**Slug Utilities:**
+
+```typescript
+import { generateSlug, generateUrlSlug, generateSnakeSlug } from '@exyconn/common/client/http';
 
-const users = await api.get('/users');
-const newUser = await api.post('/users', { name: 'John' });
-const file = await api.post('/upload', formData, withFormData());
+generateSlug('Hello World');      // 'helloWorld'
+generateUrlSlug('Hello World');   // 'hello-world'
+generateSnakeSlug('Hello World'); // 'hello_world'
 ```
 
 ---

package/dist/client/http/index.d.mts

@@ -1,85 +1,316 @@
-import { AxiosError, AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import * as axios from 'axios';
+import { AxiosResponse } from 'axios';
+export { AxiosError, AxiosResponse } from 'axios';
 
 /**
- * HTTP Client Configuration Options
+ * Response Parser Utility
+ *
+ * Comprehensive response parsing utilities for API responses.
+ * Aligned with server-side response structures.
  */
-interface HttpClientOptions {
-    baseURL: string;
-    timeout?: number;
-    withCredentials?: boolean;
-    getAuthToken?: () => string | null;
-    onUnauthorized?: () => void;
-    onServerError?: (error: AxiosError) => void;
+/**
+ * Standard API response structure from server
+ */
+interface ApiResponse<T = unknown> {
+    message: string;
+    data: T | null;
+    status: string;
+    statusCode: number;
+    paginationData?: PaginationData;
+    columns?: ColumnMetadata[];
 }
 /**
- * Create configured Axios instance
+ * Pagination metadata structure
  */
-declare const createHttpClient: (options: HttpClientOptions) => AxiosInstance;
+interface PaginationData {
+    total?: number;
+    page?: number;
+    limit?: number;
+    totalPages?: number;
+}
 /**
- * Default request config helpers
+ * Column metadata from server
  */
-declare const withFormData: () => AxiosRequestConfig;
-declare const withTimeout: (ms: number) => AxiosRequestConfig;
-declare const withAbortSignal: (signal: AbortSignal) => AxiosRequestConfig;
-
+interface ColumnMetadata {
+    name: string;
+    required: boolean;
+    datatype: string;
+}
 /**
- * Standard API Response Structure
+ * Status codes aligned with backend
  */
-interface ApiResponse<T = unknown> {
-    success: boolean;
+declare const STATUS_CODES: {
+    readonly SUCCESS: 200;
+    readonly CREATED: 201;
+    readonly NO_CONTENT: 204;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly ERROR: 500;
+};
+/**
+ * Status messages aligned with backend
+ */
+declare const STATUS_MESSAGES: {
+    SUCCESS: string;
+    CREATED: string;
+    NO_CONTENT: string;
+    BAD_REQUEST: string;
+    UNAUTHORIZED: string;
+    FORBIDDEN: string;
+    NOT_FOUND: string;
+    CONFLICT: string;
+    ERROR: string;
+};
+declare const SUCCESS_CODES: number[];
+declare const ERROR_CODES: number[];
+/**
+ * Safely extracts data from API response
+ */
+declare const parseResponseData: <T = unknown>(response: unknown, fallback?: T | null) => T | null;
+/**
+ * Extracts message from response
+ */
+declare const parseResponseMessage: (response: unknown, fallback?: string) => string;
+/**
+ * Extracts status code from response
+ */
+declare const parseResponseStatus: (response: unknown) => number | null;
+/**
+ * Extracts status message from response
+ */
+declare const parseResponseStatusMessage: (response: unknown, fallback?: string) => string;
+/**
+ * Checks if response indicates success
+ */
+declare const isSuccessResponse: (response: unknown) => boolean;
+/**
+ * Checks if response indicates error
+ */
+declare const isErrorResponse: (response: unknown) => boolean;
+/**
+ * Paginated response structure
+ */
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    page: number;
+    limit: number;
+    totalPages?: number;
+    columns?: ColumnMetadata[];
+}
+/**
+ * Parses paginated response from backend
+ */
+declare const parsePaginatedResponse: <T = unknown>(response: unknown) => PaginatedResponse<T>;
+/**
+ * Extracts specific nested data with path
+ */
+declare const extractNestedData: <T = unknown>(response: unknown, path: string, fallback?: T | null) => T | null;
+/**
+ * Safe JSON parse with fallback
+ */
+declare const safeJsonParse: <T = unknown>(json: string, fallback?: T | null) => T | null;
+/**
+ * Extracts error message from axios error response
+ */
+declare const parseAxiosErrorMessage: (error: unknown) => string;
+/**
+ * Standardized error object
+ */
+interface ParsedError {
     message: string;
-    data?: T;
-    error?: string;
-    statusCode?: number;
+    statusCode: number | null;
+    data: unknown;
+    status?: string;
 }
 /**
- * Paginated Response Structure
+ * Parses error into standardized format
  */
-interface PaginatedResponse<T = unknown> extends ApiResponse<T[]> {
-    pagination: {
-        total: number;
-        page: number;
-        limit: number;
-        totalPages: number;
-        hasNextPage: boolean;
-        hasPrevPage: boolean;
+declare const parseError: (error: unknown) => ParsedError;
+interface SimpleApiResponse {
+    data?: {
+        data?: {
+            data?: unknown;
+            meta?: Record<string, unknown>;
+        };
     };
 }
+declare const simpleParseResponse: (response: SimpleApiResponse) => unknown;
+declare const simpleMetaParseResponse: (response: SimpleApiResponse) => Record<string, unknown> | undefined;
+declare const simpleParseDualDataResponse: (response: SimpleApiResponse) => {
+    data?: unknown;
+    meta?: Record<string, unknown>;
+} | undefined;
+
+/**
+ * HTTP Configuration Interface
+ */
+interface HttpConfig {
+    baseUrl?: string;
+    apiPrefix?: string;
+    timeout?: number;
+    defaultHeaders?: Record<string, string>;
+}
+declare const axiosInstance: axios.AxiosInstance;
+/**
+ * Get current API Base URL
+ */
+declare const getApiBaseUrl: () => string;
 /**
- * Parse successful API response
+ * Set API Base URL
  */
-declare const parseResponse: <T>(response: AxiosResponse<ApiResponse<T>>) => T | null;
+declare const setApiBaseUrl: (baseUrl: string) => void;
 /**
- * Parse API response with full metadata
+ * Get current API Prefix
  */
-declare const parseFullResponse: <T>(response: AxiosResponse<ApiResponse<T>>) => ApiResponse<T>;
+declare const getApiPrefix: () => string;
 /**
- * Parse error from API response
+ * Set API Prefix
  */
-declare const parseError: (error: AxiosError<ApiResponse>) => string;
+declare const setApiPrefix: (prefix: string) => void;
+/**
+ * Get all custom headers
+ */
+declare const getCustomHeaders: () => Record<string, string>;
+/**
+ * Set a custom header globally
+ */
+declare const setCustomHeader: (key: string, value: string) => void;
+/**
+ * Remove a custom header
+ */
+declare const removeCustomHeader: (key: string) => void;
+/**
+ * Set multiple custom headers at once
+ */
+declare const setCustomHeaders: (headers: Record<string, string>) => void;
+/**
+ * Clear all custom headers
+ */
+declare const clearCustomHeaders: () => void;
+/**
+ * Configure HTTP client with custom settings
+ */
+declare const configureHttp: (config: HttpConfig) => void;
+/**
+ * Get current HTTP configuration
+ */
+declare const getHttpConfig: () => Readonly<HttpConfig>;
+/**
+ * Reset HTTP configuration to defaults
+ */
+declare const resetHttpConfig: () => void;
+/**
+ * @deprecated Use getApiBaseUrl() instead
+ */
+declare const API_BASE_URL: string;
+/**
+ * @deprecated Use getApiPrefix() instead
+ */
+declare const API_PREFIX: string;
+/**
+ * GET request
+ */
+declare const getRequest: <T = unknown>(url: string, params?: Record<string, unknown>, customHeaders?: Record<string, string>) => Promise<AxiosResponse<T>>;
+/**
+ * POST request
+ */
+declare const postRequest: <T = unknown>(url: string, data?: unknown, customHeaders?: Record<string, string>) => Promise<AxiosResponse<T>>;
+/**
+ * PUT request
+ */
+declare const putRequest: <T = unknown>(url: string, data?: unknown, customHeaders?: Record<string, string>) => Promise<AxiosResponse<T>>;
+/**
+ * PATCH request
+ */
+declare const patchRequest: <T = unknown>(url: string, data?: unknown, customHeaders?: Record<string, string>) => Promise<AxiosResponse<T>>;
+/**
+ * DELETE request
+ */
+declare const deleteRequest: <T = unknown>(url: string, params?: Record<string, unknown>, customHeaders?: Record<string, string>) => Promise<AxiosResponse<T>>;
+/**
+ * File upload with FormData
+ */
+declare const uploadFile: <T = unknown>(url: string, file: File, additionalData?: Record<string, unknown>) => Promise<AxiosResponse<T>>;
+/**
+ * Extract data from response using response-parser
+ */
+declare const extractData: <T = unknown>(response: AxiosResponse) => T | null;
+/**
+ * Extract message from response
+ */
+declare const extractMessage: (response: unknown) => string;
 /**
  * Check if response is successful
  */
-declare const isSuccess: <T>(response: AxiosResponse<ApiResponse<T>>) => boolean;
+declare const isSuccess: (response: AxiosResponse) => boolean;
+/**
+ * Extract paginated data from response
+ */
+declare const extractPaginatedData: <T = unknown>(response: AxiosResponse) => PaginatedResponse<T>;
+
 /**
- * Check if error is a specific status code
+ * Slug Utility
+ *
+ * Generates slugs from text for use in URLs and object properties.
  */
-declare const isStatusError: (error: AxiosError, statusCode: number) => boolean;
 /**
- * Check if error is unauthorized (401)
+ * Generates a camelCase slug from a given text for use in object properties
+ * @param text - The text to convert to camelCase slug
+ * @returns The generated camelCase slug
  */
-declare const isUnauthorized: (error: AxiosError) => boolean;
+declare const generateSlug: (text: string) => string;
 /**
- * Check if error is forbidden (403)
+ * Generates a kebab-case slug from a given text for use in URLs
+ * @param text - The text to convert to kebab-case slug
+ * @returns The generated kebab-case slug
  */
-declare const isForbidden: (error: AxiosError) => boolean;
+declare const generateUrlSlug: (text: string) => string;
 /**
- * Check if error is not found (404)
+ * Generates a snake_case slug from a given text
+ * @param text - The text to convert to snake_case slug
+ * @returns The generated snake_case slug
  */
-declare const isNotFound: (error: AxiosError) => boolean;
+declare const generateSnakeSlug: (text: string) => string;
+
 /**
- * Check if error is server error (5xx)
+ * Client Logger Utility
+ *
+ * Centralized logging utility that:
+ * - Only logs in development mode
+ * - Can be extended to send logs to external services (Sentry, LogRocket, etc.)
+ * - Provides consistent logging interface
  */
-declare const isServerError: (error: AxiosError) => boolean;
+interface LogOptions {
+    context?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class Logger {
+    private isDevelopment;
+    /**
+     * Log informational messages
+     */
+    info(message: string, data?: unknown, options?: LogOptions): void;
+    /**
+     * Log warning messages
+     */
+    warn(message: string, data?: unknown, options?: LogOptions): void;
+    /**
+     * Log error messages
+     */
+    error(message: string, error?: unknown, options?: LogOptions): void;
+    /**
+     * Log debug messages (only in development)
+     */
+    debug(message: string, data?: unknown, options?: LogOptions): void;
+    /**
+     * Log API errors with structured information
+     */
+    apiError(endpoint: string, error: unknown, metadata?: Record<string, unknown>): void;
+}
+declare const logger: Logger;
 
-export { type ApiResponse, type HttpClientOptions, type PaginatedResponse, createHttpClient, isForbidden, isNotFound, isServerError, isStatusError, isSuccess, isUnauthorized, parseError, parseFullResponse, parseResponse, withAbortSignal, withFormData, withTimeout };
+export { API_BASE_URL, API_PREFIX, type ApiResponse, type ColumnMetadata, ERROR_CODES, type PaginatedResponse, type PaginationData, type ParsedError, STATUS_CODES, STATUS_MESSAGES, SUCCESS_CODES, axiosInstance as axios, clearCustomHeaders, configureHttp, deleteRequest, extractData, extractMessage, extractNestedData, extractPaginatedData, generateSlug, generateSnakeSlug, generateUrlSlug, getApiBaseUrl, getApiPrefix, getCustomHeaders, getHttpConfig, getRequest, isErrorResponse, isSuccess, isSuccessResponse, logger, parseAxiosErrorMessage, parseError, parsePaginatedResponse, parseResponseData, parseResponseMessage, parseResponseStatus, parseResponseStatusMessage, patchRequest, postRequest, putRequest, removeCustomHeader, resetHttpConfig, safeJsonParse, setApiBaseUrl, setApiPrefix, setCustomHeader, setCustomHeaders, simpleMetaParseResponse, simpleParseDualDataResponse, simpleParseResponse, uploadFile };