@exyconn/common 2.1.0 → 2.3.3

package/README.md

@@ -1,6 +1,39 @@
 # @exyconn/common
 
-Common utilities, hooks, types, and data shared across all Exyconn projects (botify.life, exyconn.com, partywings.fun, sibera.work, spentiva.com).
+[![npm version](https://img.shields.io/npm/v/@exyconn/common.svg)](https://www.npmjs.com/package/@exyconn/common)
+[![CI](https://github.com/exyconn/common/actions/workflows/ci.yml/badge.svg)](https://github.com/exyconn/common/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/exyconn/common)](https://codecov.io/gh/exyconn/common)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@exyconn/common)](https://bundlephobia.com/package/@exyconn/common)
+[![Documentation](https://img.shields.io/badge/docs-common--docs.exyconn.com-blue)](https://common-docs.exyconn.com)
+
+Production-ready common utilities, hooks, types, and data shared across all Exyconn projects (botify.life, exyconn.com, partywings.fun, sibera.work, spentiva.com).
+
+## 📚 Documentation
+
+**Full documentation available at: [common-docs.exyconn.com](https://common-docs.exyconn.com)**
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Module Reference](#module-reference)
+  - [Server](#server-module)
+  - [Client](#client-module)
+  - [Shared](#shared-module)
+  - [Data](#data-module)
+- [React Hooks](#react-hooks)
+- [API Reference](#api-reference)
+- [Development](#development)
+- [Peer Dependencies](#peer-dependencies)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
 
 ## Installation
 
@@ -12,333 +45,1008 @@ yarn add @exyconn/common
 pnpm add @exyconn/common
 ```
 
+### Requirements
+
+- Node.js >= 18.0.0
+- React >= 18.0.0 (for hooks)
+- TypeScript >= 5.0.0 (recommended)
+
 ## Features
 
-- 🖥️ **Server utilities** - Response helpers, middleware, logging, database connections
-- 🌐 **Client utilities** - HTTP clients, React hooks, response parsing
-- 📝 **Shared types** - TypeScript interfaces for API responses, users, etc.
-- 🗃️ **Data modules** - Countries, currencies, phone codes, timezones, brand logos
-- ✅ **Validation** - Common patterns, regex, and validation helpers
-- 📅 **Date utilities** - Enhanced date-fns with timezone support
-- 🎨 **Brand Identity** - Complete brand configs with logos, colors, and SEO
-- 🔢 **Enums & Constants** - STATUS, SORT, ROLE, BREAKPOINTS, and more
+| Category | Description |
+|----------|-------------|
+| 🖥️ **Server utilities** | Response helpers, middleware, logging, database connections, dynamic configs |
+| 🌐 **Client utilities** | HTTP clients, React hooks (54+), response parsing |
+| 📝 **Shared types** | TypeScript interfaces for API responses, users, etc. |
+| 🗃️ **Data modules** | Countries, currencies, phone codes, timezones, brand logos |
+| ✅ **Validation** | Common patterns, regex, and validation helpers (Zod integration) |
+| 📅 **Date utilities** | Enhanced date-fns with timezone support |
+| 🎨 **Brand Identity** | Complete brand configs with logos, colors, and SEO |
+| 🔢 **Enums & Constants** | STATUS, SORT, ROLE, BREAKPOINTS, and more |
+| ⚙️ **Dynamic Configs** | Production-ready CORS, Rate Limiting, Server configs |
+| 🧪 **Fully Tested** | Comprehensive test coverage with Vitest |
+
+---
+
+## Quick Start
+
+### Import by Module (Recommended)
+
+```typescript
+// Server utilities
+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 { getRequest, postRequest, extractData, isSuccess } from '@exyconn/common/client/http';
+
+// Shared utilities
+import { isValidEmail, VALIDATION_PATTERNS } from '@exyconn/common/shared/validation';
+import { getEnv, isProd } from '@exyconn/common/shared/config';
 
-## Usage
+// Data modules
+import { countries, getCountryByCode } from '@exyconn/common/data/countries';
+import { BRANDS, getBrandById } from '@exyconn/common/data/brand-identity';
+```
 
-### Import Everything
+### Import Everything (Not Recommended for Bundle Size)
 
 ```typescript
 import { server, client, shared, data } from '@exyconn/common';
 ```
 
-### Server-side
+---
+
+## Module Reference
+
+### Server Module
+
+**Import:** `@exyconn/common/server` or specific submodules
+
+#### Server Configs (`@exyconn/common/server/configs`)
+
+Dynamic configuration system for production applications.
+
+##### ConfigBuilder
 
 ```typescript
-// Response helpers
-import { successResponse, errorResponse, paginatedResponse } from '@exyconn/common/server/response';
+import { 
+  createConfig, 
+  buildConfig, 
+  ConfigBuilder,
+  // Types
+  type AppConfig,
+  type ServerConfig,
+  type DatabaseConfig,
+  type AuthConfig,
+  type LoggingConfig,
+} from '@exyconn/common/server/configs';
 
-// Status codes & messages
-import { STATUS_CODES, STATUS_MESSAGES } from '@exyconn/common/server/enums';
+// Method 1: Using ConfigBuilder (fluent API)
+const config = createConfig()
+  .setServer({
+    name: 'my-api-server',
+    port: 4000,
+    environment: 'production',
+  })
+  .setDatabase({
+    uri: process.env.MONGODB_URI!,
+    maxPoolSize: 50,
+  })
+  .setAuth({
+    jwtSecret: process.env.JWT_SECRET!,
+    jwtExpiresIn: '7d',
+  })
+  .setLogging({
+    level: 'info',
+    file: true,
+  })
+  .addProductionOrigin('https://myapp.com')
+  .addProductionOrigin('https://api.myapp.com')
+  .addCorsPattern('.myapp.com')
+  .addRateLimitTier('upload', {
+    windowMs: 60000,
+    maxRequests: 5,
+    message: 'Upload limit exceeded',
+  })
+  .setCustom('featureFlags', { newFeature: true })
+  .loadFromEnv()
+  .build();
 
-// Winston logger
-import { createLogger, logger } from '@exyconn/common/server/logger';
+// Method 2: Quick build from partial config
+const quickConfig = buildConfig({
+  server: { name: 'quick-server', port: 3000 },
+  database: { uri: 'mongodb://localhost/mydb' },
+});
 
-// MongoDB connection
-import { connectDB } from '@exyconn/common/server/db';
+// Validate configuration
+const validation = createConfig().setServer({ name: '' }).validate();
+if (!validation.valid) {
+  console.error('Config errors:', validation.errors);
+}
+```
+
+**ConfigBuilder Methods:**
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `setServer(config)` | `Partial<ServerConfig>` | Set server configuration |
+| `setDatabase(config)` | `Partial<DatabaseConfig>` | Set database configuration |
+| `setAuth(config)` | `Partial<AuthConfig>` | Set auth configuration |
+| `setLogging(config)` | `Partial<LoggingConfig>` | Set logging configuration |
+| `setCorsOrigins(config)` | `Partial<CorsOriginsConfig>` | Set CORS origins |
+| `addProductionOrigin(origin)` | `string` | Add a production CORS origin |
+| `addDevelopmentOrigin(origin)` | `string` | Add a development CORS origin |
+| `addCorsPattern(pattern)` | `string` | Add subdomain pattern |
+| `setRateLimit(config)` | `Partial<RateLimitConfig>` | Set rate limit config |
+| `addRateLimitTier(name, tier)` | `string, RateLimitTier` | Add custom rate limit tier |
+| `setCustom(key, value)` | `string, unknown` | Set custom config value |
+| `loadFromEnv()` | - | Load config from environment variables |
+| `validate()` | - | Validate configuration, returns `{ valid, errors }` |
+| `build()` | - | Build final configuration |
 
-// Auth middleware
-import { authMiddleware, apiKeyMiddleware } from '@exyconn/common/server/middleware';
+##### CORS Configuration
+
+```typescript
+import { 
+  createCorsOptions,
+  createBrandCorsOptions,
+  createMultiBrandCorsOptions,
+  // Presets
+  DEFAULT_CORS_CONFIG,
+  EXYCONN_CORS_CONFIG,
+  STRICT_CORS_CONFIG,
+  PERMISSIVE_CORS_CONFIG,
+  // Types
+  type CorsConfig,
+} from '@exyconn/common/server/configs';
+
+// Custom CORS configuration
+const corsOptions = createCorsOptions({
+  productionOrigins: ['https://myapp.com', 'https://api.myapp.com'],
+  developmentOrigins: ['http://localhost:3000', 'http://localhost:5173'],
+  allowedSubdomains: ['.myapp.com'],
+  originPatterns: [/\.myapp\.(com|io)$/],
+  allowNoOrigin: true,       // Allow mobile apps, curl
+  allowAllInDev: true,       // Allow all in development
+  credentials: true,
+  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+  allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
+  exposedHeaders: ['X-Total-Count'],
+  maxAge: 86400,             // 24 hours preflight cache
+  customValidator: (origin) => origin.includes('trusted'), // Custom validation
+});
+
+// Single brand CORS (auto-includes www and subdomains)
+const brandCors = createBrandCorsOptions('myapp.com', {
+  credentials: true,
+});
+
+// Multi-brand CORS
+const multiBrandCors = createMultiBrandCorsOptions(
+  ['myapp.com', 'myapp.io', 'api.myapp.com'],
+  { allowNoOrigin: false }
+);
+
+// Usage with Express
+import cors from 'cors';
+app.use(cors(corsOptions));
 ```
 
-### Client-side
+**CorsConfig Options:**
+
+| Option | Type | Default | Required | Description |
+|--------|------|---------|----------|-------------|
+| `productionOrigins` | `string[]` | `[]` | No | Allowed production origins |
+| `developmentOrigins` | `string[]` | Common localhost ports | No | Allowed development origins |
+| `allowedSubdomains` | `string[]` | `[]` | No | Subdomain patterns (e.g., `.myapp.com`) |
+| `originPatterns` | `RegExp[]` | `[]` | No | Regex patterns for origin matching |
+| `allowNoOrigin` | `boolean` | `true` | No | Allow requests with no origin |
+| `allowAllInDev` | `boolean` | `true` | No | Allow all origins in development |
+| `customValidator` | `(origin: string) => boolean` | - | No | Custom origin validator |
+| `credentials` | `boolean` | `true` | No | Include credentials |
+| `methods` | `string[]` | All standard methods | No | Allowed HTTP methods |
+| `allowedHeaders` | `string[]` | Common headers | No | Allowed request headers |
+| `exposedHeaders` | `string[]` | Common response headers | No | Exposed response headers |
+| `maxAge` | `number` | `86400` | No | Preflight cache duration (seconds) |
+
+##### Rate Limiter Configuration
 
 ```typescript
-// HTTP client
-import { createHttpClient, httpGet, httpPost } from '@exyconn/common/client/http';
+import { 
+  // Factory functions
+  createRateLimiter,
+  createStandardRateLimiter,
+  createStrictRateLimiter,
+  createDdosRateLimiter,
+  createApiRateLimiter,
+  // Builder
+  rateLimiter,
+  RateLimiterBuilder,
+  // Key generators
+  defaultKeyGenerator,
+  createPrefixedKeyGenerator,
+  createUserKeyGenerator,
+  createApiKeyGenerator,
+  // Constants
+  DEFAULT_RATE_LIMIT_TIERS,
+  // Types
+  type RateLimitTierConfig,
+} from '@exyconn/common/server/configs';
+
+// Method 1: Factory functions with defaults
+const standardLimiter = createStandardRateLimiter(); // 100 req/15min
+const strictLimiter = createStrictRateLimiter();     // 20 req/15min
+const ddosLimiter = createDdosRateLimiter();         // 60 req/1min
+const apiLimiter = createApiRateLimiter();           // 30 req/1min (by API key)
+
+// Method 2: Custom configuration
+const customLimiter = createRateLimiter({
+  windowMs: 5 * 60 * 1000,    // 5 minutes
+  maxRequests: 50,
+  message: 'Too many requests, please slow down.',
+  skipSuccessfulRequests: false,
+  skipFailedRequests: false,
+}, {
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: defaultKeyGenerator,
+  skip: (req) => req.headers['x-skip-rate-limit'] === 'true',
+});
+
+// Method 3: Builder pattern (most flexible)
+const uploadLimiter = rateLimiter('STRICT')
+  .windowMinutes(5)
+  .max(10)
+  .message('Upload limit exceeded. Please wait.')
+  .keyByIp()
+  .skipWhen((req) => req.user?.isPremium)
+  .build();
+
+// User-based rate limiting
+const userLimiter = rateLimiter()
+  .windowHours(1)
+  .max(1000)
+  .keyBy((req) => req.userId || defaultKeyGenerator(req))
+  .build();
+
+// API key based rate limiting
+const apiKeyLimiter = rateLimiter('API')
+  .keyByApiKey('x-api-key')
+  .build();
 
-// React hooks
+// Usage with Express
+app.use('/api/', ddosLimiter);
+app.use('/api/', standardLimiter);
+app.post('/api/auth/login', strictLimiter);
+app.post('/api/upload', uploadLimiter);
+```
+
+**RateLimiterBuilder Methods:**
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `windowMs(ms)` | `number` | Set window in milliseconds |
+| `windowMinutes(minutes)` | `number` | Set window in minutes |
+| `windowHours(hours)` | `number` | Set window in hours |
+| `max(requests)` | `number` | Set max requests in window |
+| `message(msg)` | `string` | Set error message |
+| `skipSuccessful(skip?)` | `boolean` | Skip successful requests (default: true) |
+| `skipFailed(skip?)` | `boolean` | Skip failed requests (default: true) |
+| `keyBy(generator)` | `(req) => string` | Custom key generator |
+| `keyByIp()` | - | Key by IP address (default) |
+| `keyByApiKey(headerName?)` | `string` | Key by API key header |
+| `skipWhen(predicate)` | `(req) => boolean` | Skip when condition is true |
+| `build()` | - | Build rate limiter middleware |
+
+**Available Rate Limit Tiers:**
+
+| Tier | Window | Max Requests | Use Case |
+|------|--------|--------------|----------|
+| `STANDARD` | 15 min | 100 | General API endpoints |
+| `STRICT` | 15 min | 20 | Auth endpoints (login, signup) |
+| `DDOS` | 1 min | 60 | Global DDoS protection |
+| `VERY_STRICT` | 1 hour | 5 | Password reset, sensitive actions |
+| `RELAXED` | 15 min | 500 | High-traffic endpoints |
+| `API` | 1 min | 30 | Third-party API access |
+
+#### Response Helpers (`@exyconn/common/server/response`)
+
+```typescript
 import { 
-  useLocalStorage,
-  useDebounce,
-  useCopyToClipboard,
-  usePageTitle,
-  useSnackbar,
-  useMediaQuery,
-  useIsMobile,
-  useThemeDetector,
-  useInterval,
-  useOnClickOutside,
-  useWindowSize
-} from '@exyconn/common/client/hooks';
-
-// Utils
+  // Success responses
+  successResponse,      // 200 OK
+  successResponseArr,   // 200 OK with pagination
+  createdResponse,      // 201 Created
+  noContentResponse,    // 204 No Content
+  
+  // Error responses
+  badRequestResponse,   // 400 Bad Request
+  unauthorizedResponse, // 401 Unauthorized
+  forbiddenResponse,    // 403 Forbidden
+  notFoundResponse,     // 404 Not Found
+  conflictResponse,     // 409 Conflict
+  serverErrorResponse,  // 500 Internal Server Error
+  
+  // Utilities
+  extractColumns,
+  
+  // Types
+  type ApiResponse,
+  type PaginationData,
+  type ColumnMetadata,
+} from '@exyconn/common/server/response';
+
+// Basic success response
+app.get('/api/user/:id', async (req, res) => {
+  const user = await User.findById(req.params.id);
+  return successResponse(res, user, 'User retrieved successfully');
+});
+// Response: { status: 'success', statusCode: 200, message: '...', data: {...} }
+
+// Paginated array response (auto-extracts columns for table rendering)
+app.get('/api/users', async (req, res) => {
+  const { page = 1, limit = 10 } = req.query;
+  const users = await User.find().skip((page - 1) * limit).limit(limit);
+  const total = await User.countDocuments();
+  
+  return successResponseArr(res, users, {
+    total,
+    page,
+    limit,
+    totalPages: Math.ceil(total / limit),
+    hasNextPage: page < Math.ceil(total / limit),
+    hasPrevPage: page > 1,
+  }, 'Users retrieved');
+});
+
+// Error responses
+return badRequestResponse(res, 'Invalid email format', { field: 'email' });
+return unauthorizedResponse(res, 'Token expired');
+return forbiddenResponse(res, 'Insufficient permissions');
+return notFoundResponse(res, 'User not found');
+return serverErrorResponse(res, 'Database connection failed');
+```
+
+**Response Functions:**
+
+| Function | Status | Parameters | Description |
+|----------|--------|------------|-------------|
+| `successResponse` | 200 | `(res, data, message?)` | Standard success |
+| `successResponseArr` | 200 | `(res, data[], pagination?, message?)` | Paginated array |
+| `createdResponse` | 201 | `(res, data, message?)` | Resource created |
+| `noContentResponse` | 200* | `(res, data?, message?)` | No data found |
+| `badRequestResponse` | 400 | `(res, message?, errors?)` | Invalid request |
+| `unauthorizedResponse` | 401 | `(res, message?)` | Authentication required |
+| `forbiddenResponse` | 403 | `(res, message?)` | Access denied |
+| `notFoundResponse` | 404 | `(res, message?)` | Resource not found |
+| `conflictResponse` | 409 | `(res, message?)` | Resource conflict |
+| `serverErrorResponse` | 500 | `(res, message?, error?)` | Server error |
+
+#### Logger (`@exyconn/common/server/logger`)
+
+```typescript
 import { 
-  formatDate, 
-  copyToClipboard, 
-  toSlug,
-  isSuccessResponse,
-  getErrorMessage
-} from '@exyconn/common/client/utils';
+  createLogger, 
+  logger,            // Default instance
+  simpleLogger,      // Console-only logger
+  createMorganStream,
+  stream,            // Morgan stream for default logger
+  type LoggerConfig,
+} from '@exyconn/common/server/logger';
+
+// Default logger (writes to console + files)
+logger.info('Server started', { port: 3000 });
+logger.error('Database error', { error: err.message, stack: err.stack });
+logger.warn('Rate limit approaching');
+logger.debug('Request received', { method: 'GET', path: '/api/users' });
+
+// Custom logger
+const customLogger = createLogger({
+  level: 'debug',              // 'error' | 'warn' | 'info' | 'http' | 'debug'
+  logsDir: 'logs',             // Directory for log files
+  maxSize: '20m',              // Max file size before rotation
+  maxFiles: '14d',             // Keep logs for 14 days
+  errorMaxFiles: '30d',        // Keep error logs longer
+});
+
+// Simple logger (no files, just console)
+simpleLogger.info('Quick debug message');
+
+// With Morgan HTTP logger
+import morgan from 'morgan';
+app.use(morgan('combined', { stream }));
 ```
 
-### Shared Types
+#### Database (`@exyconn/common/server/db`)
 
 ```typescript
-import type { 
-  ApiResponse, 
-  PaginatedResponse, 
-  User, 
-  AuthResponse,
-  JwtPayload
-} from '@exyconn/common/shared/types';
+import { 
+  connectDB, 
+  disconnectDB, 
+  getConnectionStatus,
+  type DbConnectionOptions,
+} from '@exyconn/common/server/db';
+
+// Connect with default options
+await connectDB(process.env.MONGODB_URI!, {}, logger);
+
+// Connect with custom options
+await connectDB(process.env.MONGODB_URI!, {
+  maxPoolSize: 50,
+  minPoolSize: 10,
+  socketTimeoutMS: 45000,
+  retryWrites: true,
+}, logger);
+
+// Check status
+const status = getConnectionStatus(); // 'connected' | 'disconnected' | ...
+
+// Disconnect gracefully
+await disconnectDB(logger);
 ```
 
-### Validation
+#### 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,
+  optionalAuthenticateJWT,
+  authenticateApiKey,
+  extractOrganization,
+  type AuthRequest,
+} from '@exyconn/common/server/middleware';
+
+// JWT Authentication (required)
+app.use('/api/protected', authenticateJWT(process.env.JWT_SECRET!));
+
+// JWT Authentication (optional)
+app.use('/api/public', optionalAuthenticateJWT(process.env.JWT_SECRET!));
+
+// API Key Authentication
+app.use('/api/external', authenticateApiKey(async (key) => {
+  const apiKey = await ApiKey.findOne({ key, isActive: true });
+  return { valid: !!apiKey, organizationId: apiKey?.organizationId };
+}));
+
+// Access auth data in routes
+app.get('/api/profile', authenticateJWT(secret), (req: AuthRequest, res) => {
+  const userId = req.userId;
+  const orgId = req.organizationId;
+});
+```
+
+#### Server Utils (`@exyconn/common/server/utils`)
+
+```typescript
+import { 
+  buildFilter, 
+  buildPagination, 
+  buildPaginationMeta,
+} from '@exyconn/common/server/utils';
+
+// Build MongoDB filter dynamically
+const filter = buildFilter({
+  organizationId: req.organizationId,
+  search: req.query.q,
+  searchFields: ['name', 'email', 'phone'],
+  status: req.query.status,
+  startDate: req.query.from,
+  endDate: req.query.to,
+});
+
+// Calculate pagination
+const pagination = buildPagination({
+  page: parseInt(req.query.page) || 1,
+  limit: parseInt(req.query.limit),
+  defaultLimit: 10,
+  maxLimit: 100,
+});
+
+// Build pagination meta
+const meta = buildPaginationMeta(totalCount, pagination.page, pagination.limit);
+```
+
+---
+
+### Client Module
+
+**Import:** `@exyconn/common/client` or specific submodules
+
+#### React Hooks (`@exyconn/common/client/hooks`)
+
+50+ production-ready React hooks organized by category.
+
+##### State & Logic Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useToggle` | Boolean toggle | `const [isOpen, toggle] = useToggle(false)` |
+| `useCounter` | Numeric counter | `const { count, increment, decrement } = useCounter(0)` |
+| `usePrevious` | Track previous value | `const prevValue = usePrevious(value)` |
+| `useObjectState` | Partial state updates | `const [state, setState] = useObjectState({ a: 1 })` |
+| `useHistoryState` | State with undo/redo | `const [value, setValue, { undo, redo }] = useHistoryState('')` |
+| `useList` | Array operations | `const [list, { push, removeAt }] = useList([])` |
+| `useMap` | Map operations | `const [map, { set, remove }] = useMap()` |
+| `useSet` | Set operations | `const [set, { add, toggle }] = useSet()` |
+
+##### Side Effects & Timing Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useDebounce` | Debounce value | `const debouncedSearch = useDebounce(search, 500)` |
+| `useThrottle` | Throttle value | `const throttled = useThrottle(value, 100)` |
+| `useTimeout` | Execute after delay | `const { reset, clear } = useTimeout(fn, 3000)` |
+| `useInterval` | Repeated execution | `const { start, stop } = useInterval(fn, 1000)` |
+| `useCountdown` | Countdown timer | `const { count, start, stop } = useCountdown({ seconds: 60 })` |
+
+##### Browser & Document Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useWindowSize` | Track dimensions | `const { width, height } = useWindowSize()` |
+| `useWindowScroll` | Track scroll | `const { y, scrollToTop } = useWindowScroll()` |
+| `useDocumentTitle` | Set title | `useDocumentTitle('My Page')` |
+| `useVisibilityChange` | Tab visibility | `const isVisible = useVisibilityChange()` |
+| `useLockBodyScroll` | Prevent scroll | `useLockBodyScroll(isModalOpen)` |
+| `useIsClient` | Client check | `const isClient = useIsClient()` |
+
+##### Events & Interaction Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useEventListener` | Attach events | `useEventListener('keydown', handler)` |
+| `useKeyPress` | Detect key | `const isEnter = useKeyPress('Enter')` |
+| `useHover` | Track hover | `const [ref, isHovered] = useHover()` |
+| `useClickAway` | Click outside | `useClickAway(ref, closeHandler)` |
+| `useLongPress` | Long press | `const props = useLongPress(handler, { delay: 500 })` |
+| `useCopyToClipboard` | Copy text | `const [copied, copy] = useCopyToClipboard()` |
+
+##### Media & Device Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useMediaQuery` | Responsive | `const isMobile = useMediaQuery('(max-width: 768px)')` |
+| `useBattery` | Battery status | `const { level, charging } = useBattery()` |
+| `useNetworkState` | Network info | `const { online, effectiveType } = useNetworkState()` |
+| `useIdle` | User inactivity | `const isIdle = useIdle(30000)` |
+| `useGeolocation` | User location | `const { latitude, longitude } = useGeolocation()` |
+| `useThemeDetector` | System theme | `const isDark = useThemeDetector()` |
+
+##### Storage Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useLocalStorage` | Persist in localStorage | `const [value, setValue] = useLocalStorage('key', initial)` |
+| `useSessionStorage` | Session storage | `const [value, setValue] = useSessionStorage('key', initial)` |
+
+##### Data Fetching Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useFetch` | Data fetching | `const { data, loading, error } = useFetch('/api/data')` |
+| `useScript` | Load scripts | `const { loaded, error } = useScript('https://...')` |
+
+##### Performance Hooks
+
+| Hook | Description | Example |
+|------|-------------|---------|
+| `useRenderCount` | Count renders | `const count = useRenderCount()` |
+| `useMeasure` | Element dimensions | `const [ref, { width, height }] = useMeasure()` |
+| `useIntersectionObserver` | Visibility detection | `const [ref, entry] = useIntersectionObserver()` |
+
+#### HTTP Client (`@exyconn/common/client/http`)
+
+```typescript
+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!');
+}
+
+// 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';
+
+generateSlug('Hello World');      // 'helloWorld'
+generateUrlSlug('Hello World');   // 'hello-world'
+generateSnakeSlug('Hello World'); // 'hello_world'
+```
+
+---
+
+### Shared Module
+
+**Import:** `@exyconn/common/shared` or specific submodules
+
+#### Validation (`@exyconn/common/shared/validation`)
 
 ```typescript
 import { 
   VALIDATION_PATTERNS,
-  VALIDATION_MESSAGES,
   isValidEmail,
   isValidPassword,
   isValidPhone,
-  isValidUrl
+  isValidUrl,
 } from '@exyconn/common/shared/validation';
+
+isValidEmail('test@example.com'); // true
+isValidPassword('Password1!', 'strong'); // true
+isValidPhone('+1 234 567 8901'); // true
+
+// Use patterns directly
+VALIDATION_PATTERNS.EMAIL.test('test@example.com');
+VALIDATION_PATTERNS.SLUG.test('my-blog-post');
 ```
 
-### Date/Time Utilities
+**Available Patterns:**
+
+| Pattern | Description |
+|---------|-------------|
+| `EMAIL` | Email validation |
+| `PASSWORD_STRONG` | Strong password (8+ chars, upper, lower, number, special) |
+| `PASSWORD_MEDIUM` | Medium password (8+ chars, upper, lower, number) |
+| `PHONE_INTERNATIONAL` | International phone |
+| `URL` / `URL_STRICT` | URL validation |
+| `SLUG` | Kebab-case slug |
+| `USERNAME` | Username (3-30 chars, alphanumeric, _, -) |
+| `IPV4` | IPv4 address |
+| `HEX_COLOR` | Hex color code |
+| `DATE_ISO` | ISO date format |
+
+#### Environment Config (`@exyconn/common/shared/config`)
 
 ```typescript
-import { 
-  formatDate,
-  formatDateTime,
-  formatDateInTimezone,
-  formatRelativeTime,
-  formatSmartDate,
-  toTimezone,
-  fromTimezone,
-  nowInTimezone,
-  addTime,
-  subtractTime,
-  getDayBoundaries,
-  getAge,
-  isWeekend,
-  DATE_FORMATS
-} from '@exyconn/common/shared';
+import { getEnv, getEnvOptional, isProd, isDev, validateEnv } from '@exyconn/common/shared/config';
+
+const port = getEnv('PORT', 3000);           // Returns number
+const secret = getEnv('JWT_SECRET');         // Required, throws if missing
+const optional = getEnvOptional('OPTIONAL'); // Returns undefined if missing
+
+if (isProd()) { /* Production only */ }
+if (isDev()) { /* Development only */ }
+
+validateEnv(['DATABASE_URL', 'JWT_SECRET']); // Throws with missing vars
 ```
 
-### Data Modules
+---
+
+### Data Module
+
+**Import:** `@exyconn/common/data` or specific files
+
+#### Countries (`@exyconn/common/data/countries`)
 
 ```typescript
-// Countries with nested states/cities + flags
 import { 
-  countries, 
-  getCountryByCode, 
-  getStatesByCountry, 
-  getCitiesByState,
+  default as countries,
+  getCountryByCode,
+  getStatesByCountry,
   searchCountries,
   getFlag,
-  getAllCountriesWithFlags,
-  codeToFlag
 } from '@exyconn/common/data/countries';
 
-// Currencies
-import { 
-  currencies, 
-  getCurrencyByCode, 
-  formatCurrency,
-  formatCurrencyNative
-} from '@exyconn/common/data/currencies';
+const usa = getCountryByCode('US');
+const states = getStatesByCountry('US');
+const matches = searchCountries('united');
+const flag = getFlag('US'); // '🇺🇸'
+```
 
-// Phone codes
-import { phoneCodes, getPhoneCodeByCountry } from '@exyconn/common/data/phone-codes';
+#### Currencies (`@exyconn/common/data/currencies`)
 
-// Timezones
-import { 
-  timezones, 
-  getTimezoneByCode, 
-  searchTimezones,
-  getCommonTimezones
-} from '@exyconn/common/data/timezones';
+```typescript
+import { getCurrencyByCode, formatCurrency } from '@exyconn/common/data/currencies';
 
-// Regex patterns
-import { 
-  REGEX,
-  EMAIL,
-  PASSWORD_STRONG,
-  PHONE_INTERNATIONAL,
-  UUID,
-  URL_STRICT
-} from '@exyconn/common/data/regex';
-
-// Brand Identity
-import {
-  BRANDS,
-  APPS,
-  getBrandById,
-  getBrandByDomain,
-  getThemedLogo,
-  createAppConfig
-} from '@exyconn/common/data/brand-identity';
+const usd = getCurrencyByCode('USD');
+formatCurrency(1234.56, 'USD'); // '$1,234.56'
 ```
 
-### Enums & Constants
+#### Phone Codes (`@exyconn/common/data/phone-codes`)
 
 ```typescript
-import {
-  // Status enums
-  STATUS,
-  USER_STATUS,
-  ORDER_STATUS,
-  PAYMENT_STATUS,
-  TASK_STATUS,
-  
-  // Sort options
-  SORT,
-  SORT_DIRECTION,
-  
-  // Roles & permissions
-  ROLE,
-  PERMISSION_LEVEL,
-  
-  // UI constants
-  BREAKPOINTS,
-  MEDIA_QUERIES,
-  THEME,
-  
-  // Other
-  PRIORITY,
-  VISIBILITY,
-  NOTIFICATION_TYPE
-} from '@exyconn/common/shared/constants/enums';
+import { getPhoneCodeByCountry } from '@exyconn/common/data/phone-codes';
+
+const usCode = getPhoneCodeByCountry('US');
+// { country: 'United States', dial_code: '+1', flag: '🇺🇸' }
 ```
 
-## Data Module Details
-
-### Countries
-- 50+ countries with full details
-- Nested states/cities for major countries
-- Includes phone codes, currencies, timezones
-- **NEW:** Emoji flags with `getFlag()` and `codeToFlag()` helpers
-
-### Currencies
-- 100+ world currencies
-- Symbol, name, and native formatting
-- formatCurrency(amount, code) helper
-
-### Phone Codes
-- 190+ international phone codes
-- Country flags (emoji)
-
-### Timezones
-- 65+ timezones with UTC offsets
-- Common timezone presets
-- Search and filter functions
-
-### Regex Patterns
-100+ common regex patterns organized by category:
-- **Email** - Basic, RFC5322, common domains
-- **Password** - Weak to very strong
-- **Phone** - International, US, India, UK
-- **Postal** - ZIP, PIN, UK, Canada, Germany
-- **IDs** - UUID, MongoDB ObjectId, Aadhaar, PAN, SSN
-- **URL** - Basic, strict, domain, localhost
-- **Credit Card** - Visa, Mastercard, Amex, etc.
-- **Date/Time** - ISO, various formats
-- **Colors** - Hex, RGB, RGBA, HSL
-- **And more!**
-
-### Brand Identity
-Complete brand configuration for all 5 Exyconn projects:
-- **Logo variants:** light, dark, logoOnly, darkLogoOnly
-- **Colors:** primary, secondary, accent
-- **Contact:** support email, sales email
-- **Social links:** Twitter, LinkedIn, GitHub, etc.
-- **SEO config:** title, description, keywords
-
-Projects:
-- **botify.life** - AI/Bot platform
-- **exyconn.com** - Main Exyconn brand
-- **partywings.fun** - Event platform
-- **sibera.work** - Work management
-- **spentiva.com** - Finance platform
-
-### Enums & Breakpoints
-Comprehensive enums for consistent data handling:
-- **STATUS** - active, pending, approved, archived...
-- **USER_STATUS** - active, suspended, banned...
-- **ORDER_STATUS** - pending, confirmed, shipped...
-- **PAYMENT_STATUS** - pending, completed, refunded...
-- **TASK_STATUS** - todo, in_progress, done...
-- **SORT** - newest, oldest, alphabetical, popular...
-- **ROLE** - super_admin, admin, user, viewer...
-- **PRIORITY** - low, medium, high, critical
-- **BREAKPOINTS** - xs, sm, md, lg, xl, 2xl (Tailwind-compatible)
-
-## React Hooks
-
-| Hook | Description |
-|------|-------------|
-| useLocalStorage | Persist state in localStorage with cross-tab sync |
-| useDebounce | Debounce a value with configurable delay |
-| useCopyToClipboard | Copy text to clipboard with status |
-| usePageTitle | Set document title with suffix |
-| useSnackbar | Toast/snackbar notification state |
-| useMediaQuery | Track media query matches |
-| useIsMobile / useIsDesktop | Responsive breakpoint hooks |
-| useThemeDetector | Detect system light/dark mode |
-| useInterval | Safely run intervals with cleanup |
-| useOnClickOutside | Detect clicks outside element |
-| useWindowSize | Track window dimensions |
+#### Timezones (`@exyconn/common/data/timezones`)
 
-## Peer Dependencies
+```typescript
+import { getTimezoneByCode, searchTimezones } from '@exyconn/common/data/timezones';
 
-All peer dependencies are optional - only install what you need:
-
-```json
-{
-  "axios": "^1.6.0",
-  "date-fns": "^3.0.0",
-  "date-fns-tz": "^3.0.0",
-  "express": "^4.18.0",
-  "jsonwebtoken": "^9.0.0",
-  "mongoose": "^8.0.0",
-  "react": "^18.0.0",
-  "winston": "^3.11.0"
-}
+const pst = getTimezoneByCode('America/Los_Angeles');
+const matches = searchTimezones('india');
+```
+
+#### Regex Patterns (`@exyconn/common/data/regex`)
+
+```typescript
+import REGEX from '@exyconn/common/data/regex';
+
+REGEX.EMAIL.BASIC.test('test@example.com');
+REGEX.PASSWORD.STRONG.test('Test@123');
+REGEX.CREDIT_CARD.VISA.test('4111111111111111');
 ```
 
-## Package Exports
+#### Brand Identity (`@exyconn/common/data/brand-identity`)
+
+```typescript
+import { BRANDS, getBrandById, getBrandByDomain, getThemedLogo } from '@exyconn/common/data/brand-identity';
+
+const exyconn = getBrandById('exyconn');
+const brand = getBrandByDomain('botify.life');
+const logo = getThemedLogo('exyconn', 'dark');
+```
+
+---
+
+## Package Exports Map
 
 ```
 @exyconn/common
-├── /server              # Server-side utilities
-│   ├── /response        # Response helpers
-│   ├── /enums           # Status codes/messages
-│   ├── /logger          # Winston logger
-│   ├── /db              # Database connections
-│   ├── /middleware      # Auth middleware
-│   └── /utils           # Server utilities
-├── /client              # Client-side utilities
-│   ├── /http            # Axios HTTP client
-│   ├── /hooks           # React hooks
-│   ├── /logger          # Browser logger
-│   └── /utils           # Client utilities
-├── /shared              # Shared between server/client
-│   ├── /types           # TypeScript types
-│   ├── /validation      # Validation patterns
-│   ├── /constants       # Enums, breakpoints, status codes
-│   └── /utils           # Date-time utilities
-└── /data                # Static data modules
-    ├── /countries       # Countries with states/cities/flags
-    ├── /currencies      # World currencies
-    ├── /phone-codes     # International phone codes
-    ├── /timezones       # Timezones
-    ├── /regex           # Common regex patterns
-    ├── /brand-identity  # Complete brand configs
-    └── /logos           # Brand logos (deprecated, use brand-identity)
+├── /server                    # Server utilities
+│   ├── /response              # Response helpers
+│   ├── /enums                 # Status codes/messages
+│   ├── /logger                # Winston logger
+│   ├── /db                    # Database connections
+│   ├── /middleware            # Auth middleware
+│   ├── /utils                 # Server utilities
+│   └── /configs               # Dynamic configurations
+├── /client                    # Client utilities
+│   ├── /http                  # Axios HTTP client
+│   ├── /hooks                 # React hooks (50+)
+│   ├── /logger                # Browser logger
+│   ├── /utils                 # Client utilities
+│   └── /web                   # Web utilities
+├── /shared                    # Shared between server/client
+│   ├── /types                 # TypeScript types
+│   ├── /validation            # Validation patterns
+│   ├── /constants             # Enums, breakpoints
+│   ├── /config                # Environment config
+│   └── /utils                 # Date-time utilities
+└── /data                      # Static data modules
+    ├── /countries             # Countries with states/cities
+    ├── /currencies            # World currencies
+    ├── /phone-codes           # Phone codes
+    ├── /timezones             # Timezones
+    ├── /regex                 # Regex patterns
+    └── /brand-identity        # Brand configs
+```
+
+---
+
+## Peer Dependencies
+
+All peer dependencies are **optional**. Install only what you need:
+
+| Package | Version | Required For |
+|---------|---------|--------------|
+| `react` | ^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0 | Client hooks |
+| `express` | ^4.18.0 \|\| ^5.0.0 | Server utilities |
+| `express-rate-limit` | ^7.0.0 | Rate limiter configs |
+| `cors` | ^2.8.5 | CORS configs |
+| `mongoose` | ^8.0.0 | Database utilities |
+| `winston` | ^3.11.0 | Server logger |
+| `jsonwebtoken` | ^9.0.0 | Auth middleware |
+| `axios` | ^1.6.0 | HTTP client |
+| `date-fns` | ^3.0.0 | Date utilities |
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type { 
+  ApiResponse, 
+  CorsConfig, 
+  RateLimitTierConfig,
+  AuthRequest,
+} from '@exyconn/common/server';
 ```
 
+---
+
+## Node.js Version
+
+Requires Node.js >= 18.0.0
+
+---
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/exyconn/common.git
+cd common
+
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm run test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build the package with tsup |
+| `npm run dev` | Watch mode for development |
+| `npm run test` | Run tests with Vitest |
+| `npm run test:coverage` | Run tests with coverage report |
+| `npm run lint` | Lint the codebase |
+| `npm run type-check` | TypeScript type checking |
+| `npm run docs:dev` | Start docs dev server (port 4006) |
+| `npm run docs:build` | Build documentation |
+| `npm run docs:start` | Start production docs server |
+
+### Documentation Development
+
+```bash
+# Install docs dependencies
+npm run docs:install
+
+# Start documentation site locally
+npm run docs:dev
+
+# Open http://localhost:4006
+```
+
+### Running with Docker
+
+```bash
+# Build the docs Docker image
+cd docs
+docker build -t common-docs .
+
+# Run the container
+docker run -p 4006:4006 common-docs
+```
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` - New features
+- `fix:` - Bug fixes
+- `docs:` - Documentation changes
+- `test:` - Adding or updating tests
+- `refactor:` - Code refactoring
+- `chore:` - Maintenance tasks
+
+---
+
 ## License
 
 MIT © Exyconn