# Common Package

Shared utilities, base classes, errors, types, ports, and middlewares used across all packages. Imported as `@humand-packages/common`.

## Base Classes

| Class | Purpose |
|-------|---------|
| `BaseController` | Express controller base with `endpointHandlerWithGenerics` for transactional endpoints |
| `BaseRepositoryPort` | Abstract port with `getTransaction`, `transactionWithRetries`, `transactionWithAdvisoryLock` |
| `ValidationClass` | Marker base class for request validation (class-validator) |
| `SerializationClass<Domain, DTO>` | Generic serialization with `serialize()` (abstract) and `serializeList()` |

Note: `BaseRepositoryAdapter` lives in `monolith` (`src/api/dbAdapters/baseRepositoryAdapter.ts`), not here.

## Error Classes

All extend `GenericError`. Located in `src/business/errors/`.

| Error | HTTP Status |
|-------|-------------|
| `BadRequestError` | 400 |
| `UnauthorizedError` | 401 |
| `ForbiddenError` | 403 |
| `NotFoundError` | 404 |
| `NotAcceptableError` | 406 |
| `RequestConflictError` | 409 |
| `GoneError` | 410 |
| `UnprocessableEntityError` | 422 |
| `ResourceLockedError` | 423 |
| `TooManyRequestsError` | 429 |
| `InternalServerError` | 500 |
| `ServiceUnavailableError` | 503 |

Always provide an `ErrorCodes` enum value (500+ codes in `src/business/errors/errorCodes.ts`) — never raw strings.

## Key Types

- `OptionalNullable<T>` — makes nullable properties optional, keeps non-nullable required. Used in all `ForCreation` domain model constructors.
- `Page<T>` — paginated response type
- Queue types: `QUEUES` enum, `QueueMessageTypes` enum

## Ports

Abstract port interfaces in `src/business/ports/`:

`baseRepositoryPort`, `cachePort`, `deferredExecutionQueuePort`, `eventEmitterPort`, `loggerPort`, `messagingBotPort`, `metricRecorderPort`, `queuePort`, `searchEnginePort`, `translationsPort`, `utilsPort`

## Middlewares

Request processing middlewares in `src/presentation/middlewares/`:

`bodyParamsValidator`, `cursorPaginationValidator`, `pageLimitPaginationValidator`, `sortingParamsValidator`, `files`, `excelMimeTypes`, `throttle` (token-bucket rate limiter, Redis-backed; YAML rules + multi-signature matching — see `docs/throttle.md`)

## Shared Validation Classes

`paginableVC`, `sortableVC`, `filterableVC` — extend these when building list endpoints.

## Guidelines

- This package is imported by all others. Changes here affect the entire codebase.
- Do not add module-specific logic here. Only truly shared utilities.
- Extract to common only when 3+ modules need the same functionality.
- Always confirm with the user before modifying this package.

See also: extracted packages that depend on common (e.g. `humand-packages/scheduled-actions/AGENTS.md`).