@sgs-workflow/shared

Paquete compartido de utilidades, tipos y middleware para las APIs de SGS Workflow.

Descripción

Este paquete contiene código compartido que es utilizado por múltiples APIs del ecosistema SGS Workflow:
- server - API principal de workflow
- files-server - API de gestión de archivos
- security-api - API de autenticación y autorización

Estructura

``
shared/
├── utils/ # Utilidades compartidas
│ ├── db-actions.ts # Acciones CRUD de base de datos
│ ├── filter-processor.ts # Procesador de filtros
│ ├── filter-parser.ts # Parser de filtros
│ └── condition-processor.ts # Procesador de condiciones
├── types/ # Tipos TypeScript compartidos
│ ├── auth.types.ts # Tipos de autenticación
│ ├── db-actions.types.ts # Tipos de acciones DB
│ ├── instances.types.ts # Tipos de instancias
│ └── index.ts # Exportaciones (incluye HttpStatus enum)
├── middleware/ # Middleware compartido
│ ├── error-handler.ts # Manejador de errores (incluye AppError, asyncHandler)
│ └── index.ts # Exportaciones
├── response/ # Helpers de respuesta
│ ├── api-response.ts # Formato de respuestas API
│ └── index.ts # Exportaciones
└── package.json # Configuración del paquete
`

Instalación

Este paquete es interno del monorepo y se instala automáticamente con pnpm workspaces:

`bash
cd migration/backend
pnpm install
`

Uso

$3

`typescript
// Importar utilidades de DB
import { list, data, publish, remove } from '@sgs-workflow/shared/utils/db-actions';

// Importar tipos
import type { ListParams, ListResponse } from '@sgs-workflow/shared/types/db-actions.types';
import type { UserSession, Instance } from '@sgs-workflow/shared/types/instances.types';

// Importar middleware
import { errorHandler } from '@sgs-workflow/shared/middleware/error-handler';

// Importar response helpers
import { ApiResponseHelper, sendResponse } from '@sgs-workflow/shared/response/api-response';
`

APIs Disponibles

$3

#### db-actions.ts

Operaciones CRUD para Sequelize:

`typescript
// Listar con paginación
const result = await list(model, {
start: 0,
limit: 20,
where: { status: 'active' },
order: 'id',
asc: 'DESC'
}, '/endpoint');

// Obtener por ID
const item = await data(model, { id: 1 }, '/endpoint');

// Crear o actualizar
const saved = await publish(model, { id: 1, name: 'Updated' }, '/endpoint');

// Eliminar
const deleted = await remove(model, { id: 1 }, '/endpoint');
`

#### filter-processor.ts

Procesa filtros complejos para queries:

`typescript
const filters = processFilters(model, {
name: { _like: '%test%' },
status: { _in: ['active', 'pending'] },
createdAt: { _gte: '2024-01-01' }
});
`

#### condition-processor.ts

Procesa condiciones con operadores de Sequelize:

`typescript
const condition = processCondition({
field: 'age',
operator: '_gte',
value: 18
});
`

$3

#### instances.types.ts

Tipos para workflow instances:
- Instance - Instancia de workflow
- ListInstancesParams - Parámetros de listado
- UserSession - Sesión de usuario
- ViewType - Tipos de vista
- etc.

#### db-actions.types.ts

Tipos para acciones de DB:
- ListParams - Parámetros de listado
- ListResponse - Respuesta de listado
- DataResponse - Respuesta de data
- PublishResponse - Respuesta de publicación

$3

#### error-handler.ts

Middleware de manejo de errores con clases y utilidades:

`typescript
import { errorHandler, notFoundHandler, AppError, asyncHandler } from '@sgs-workflow/shared/middleware';
import { HttpStatus } from '@sgs-workflow/shared/types';

// Registrar middleware
app.use(notFoundHandler);
app.use(errorHandler);

// Usar AppError para errores controlados
throw new AppError('User not found', HttpStatus.NOT_FOUND);
throw new AppError('Invalid input', HttpStatus.BAD_REQUEST, true, { field: 'email' });

// Usar asyncHandler para envolver rutas async
router.get('/users', asyncHandler(async (req, res) => {
const users = await userService.getAll();
res.json(ApiResponseHelper.success(users).body);
}));
`

$3

#### HttpStatus enum

Códigos HTTP estándar:

`typescript
import { HttpStatus } from '@sgs-workflow/shared/types';

HttpStatus.OK // 200
HttpStatus.CREATED // 201
HttpStatus.BAD_REQUEST // 400
HttpStatus.UNAUTHORIZED // 401
HttpStatus.FORBIDDEN // 403
HttpStatus.NOT_FOUND // 404
HttpStatus.INTERNAL_SERVER_ERROR // 500
HttpStatus.SERVICE_UNAVAILABLE // 503
`

$3

#### api-response.ts

Helpers para formatear respuestas:

`typescript
// Success response
const response = ApiResponseHelper.success({ data: items });
sendResponse(res, response);

// Error responses
const notFound = ApiResponseHelper.notFound('Item not found');
const badRequest = ApiResponseHelper.badRequest('Invalid input');
const unauthorized = ApiResponseHelper.unauthorized('Invalid token');
const internalError = ApiResponseHelper.internalError(error);
`

Desarrollo

$3

`bash
cd shared
pnpm type-check
`

$3

1. Crear archivo en el directorio apropiado
2. Exportar en index.ts
3. Documentar en este README

$3

1. Crear archivo en types/
2. Exportar en types/index.ts
3. Documentar la interfaz

Versionamiento

Este paquete usa versionamiento semántico:
- 1.0.1 - Actualización de dependencias y mejoras
- 1.0.0` - Versión inicial con funcionalidades base

Licencia

UNLICENSED - Uso interno