@hed-hog/core 0.0.270 → 0.0.273

package/README.md

@@ -0,0 +1,402 @@
+# @hed-hog/core
+
+## 1. Visão geral do módulo
+
+O módulo `@hed-hog/core` é o núcleo do monorepo HedHog, responsável por fornecer funcionalidades centrais essenciais para o sistema, incluindo autenticação, inteligência artificial, dashboard, sistema e gerenciamento de usuários, roles, permissões e componentes de interface. Ele integra diversos submódulos que tratam desde a segurança e autenticação até a gestão de dashboards customizáveis e agentes de IA.
+
+## 2. Escopo e responsabilidades
+
+- Gerenciamento de autenticação e autorização, incluindo MFA, WebAuthn, recuperação de senha e sessões.
+- Serviços de inteligência artificial para chat e agentes AI com suporte a OpenAI e Gemini.
+- Gestão de dashboards, componentes, roles e usuários associados.
+- Informações do sistema operacional, hardware, banco de dados e módulos instalados.
+- Validação e manipulação de dados via DTOs e integração com Prisma ORM.
+- Suporte a internacionalização e paginação.
+
+## 3. Endpoints
+
+### Módulo AI (`/ai`)
+
+| Método | Path                  | Autenticação | Descrição                                      | Parâmetros / Body                                                                                  | Resposta                                                                                      | Erros Comuns                          |
+|--------|-----------------------|--------------|------------------------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------|
+| POST   | `/ai/chat`            | Autenticada  | Realiza chat com IA, podendo enviar arquivo.   | Body: `ChatDTO` (message, provider?, model?, systemPrompt?, file_id?)<br>File: opcional           | `{ provider, model, content }`                                                               | 400: Chave API não configurada      |
+| POST   | `/ai/agent`           | Autenticada  | Cria um agente AI.                              | Body: `CreateAgentDTO` (slug, provider?, model?, instructions?)                                   | Objeto agente criado ou existente                                                           | 400: Slug já existe                 |
+| GET    | `/ai/agent`           | Autenticada  | Lista agentes AI com paginação.                 | Query: paginação (page, pageSize, search)                                                        | Paginação com lista de agentes                                                              | -                                   |
+| GET    | `/ai/agent/id/:agentId` | Autenticada | Obtém agente AI por ID.                         | Path param: `agentId` (int)                                                                      | Objeto agente                                                                              | 404: Agente não encontrado          |
+| GET    | `/ai/agent/:slug`     | Autenticada  | Obtém agente AI por slug.                        | Path param: `slug` (string)                                                                      | Objeto agente                                                                              | 404: Agente não encontrado          |
+| PATCH  | `/ai/agent/:agentId`  | Autenticada  | Atualiza agente AI.                             | Path param: `agentId` (int)<br>Body: `UpdateAgentDTO` (slug?, provider?, model?, instructions?)  | Objeto agente atualizado                                                                   | 404: Agente não encontrado<br>400: Slug duplicado |
+| DELETE | `/ai/agent`           | Autenticada  | Deleta agentes AI em lote.                      | Body: `DeleteDTO` (ids: number[])                                                                | `{ count: number }`                                                                         | 404: Um ou mais agentes não encontrados |
+| POST   | `/ai/agent/:slug/chat`| Autenticada  | Chat com agente AI específico, com arquivo opcional. | Path param: `slug` (string)<br>Body: `ChatAgentDTO` (message, file_id?)<br>File: opcional         | `{ slug, provider, model, content }`                                                       | 404: Agente não encontrado          |
+
+### Módulo Auth (`/auth`)
+
+| Método | Path                          | Autenticação | Descrição                                      | Parâmetros / Body                                                                                  | Resposta                                                                                      | Erros Comuns                          |
+|--------|-------------------------------|--------------|------------------------------------------------|--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------|
+| GET    | `/auth/verify`                | Autenticada  | Verifica usuário autenticado.                   | -                                                                                                | Dados do usuário autenticado                                                                | -                                   |
+| GET    | `/auth/roles`                 | Pública      | Retorna roles do usuário (se autenticado).     | -                                                                                                | `{ roles: string[] }`                                                                        | -                                   |
+| POST   | `/auth/refresh`               | Pública      | Atualiza token de acesso usando refresh token. | Body: `{ refreshToken?: string }`<br>Cookies: `rt` opcional                                      | `{ accessToken, refreshToken? }`                                                            | 400: Refresh token não fornecido    |
+| POST   | `/auth/login`                 | Pública      | Login com email e senha.                         | Body: `LoginDTO` (email, password, refreshToken?)                                               | Tokens de acesso e refresh ou MFA requerida                                                | 400: Acesso negado                   |
+| POST   | `/auth/login-email-verification` | Pública  | Login via verificação por email e código.       | Body: `LoginEmailVerificationDTO` (token, code)                                                 | Tokens de acesso e refresh                                                                  | 400: Código inválido ou desafio não encontrado |
+| POST   | `/auth/login-email-verification-resend` | Pública | Reenvia código de verificação por email.        | Body: `LoginEmailVerificationResendDTO` (token)                                                 | Novo token para verificação                                                                 | 400: Token inválido ou expirado     |
+| POST   | `/auth/signup`                | Pública      | Cadastro com email e senha.                      | Body: `CreateWithEmailAndPasswordDTO`                                                           | Usuário criado                                                                             | -                                   |
+| POST   | `/auth/login-code`            | Pública      | Login com código MFA.                            | Body: `LoginWithCodeDTO` (token, code, methodType?)                                             | Tokens de acesso e refresh                                                                  | 400: Código MFA inválido            |
+| POST   | `/auth/login-recovery-code`   | Pública      | Login com código de recuperação MFA.            | Body: `LoginWithRecoveryCodeDTO` (token, code)                                                  | Tokens de acesso e refresh                                                                  | 400: Código de recuperação inválido|
+| POST   | `/auth/resend-mfa-code`       | Pública      | Reenvia código MFA por email.                    | Body: `ResendMfaCodeDTO` (token)                                                                | `{ success: true, hasEmailMfa: true }`                                                     | 400: Nenhum método MFA por email    |
+| POST   | `/auth/webauthn/generate`     | Pública      | Gera opções para autenticação WebAuthn.          | Body: `{ mfaToken: string }`                                                                     | Opções WebAuthn                                                                            | 400: WebAuthn não configurado       |
+| POST   | `/auth/webauthn/verify`       | Pública      | Verifica autenticação WebAuthn.                   | Body: `{ mfaToken: string, assertionResponse: any }`                                            | Tokens de acesso e refresh                                                                  | 400: Verificação falhou             |
+| POST   | `/auth/forgot`                | Pública      | Solicita recuperação de senha via email.         | Body: `ForgetDTO` (email)                                                                        | `{ success: true }`                                                                         | -                                   |
+| POST   | `/auth/logout`                | Pública      | Logout e invalida refresh token.                  | Body: `{ refreshToken?: string }`<br>Cookies: `rt` opcional                                      | `{ success: true }`                                                                         | 400: Refresh token não fornecido    |
+| POST   | `/auth/forgot-reset`          | Pública      | Reseta senha via código de recuperação.           | Body: `ResetDTO` (password, code)                                                               | Tokens de acesso e refresh                                                                  | 400: Código inválido ou expirado    |
+
+### Módulo System (`/system`)
+
+| Método | Path       | Autenticação | Descrição                         | Parâmetros / Body | Resposta                                                                                  | Erros Comuns |
+|--------|------------|--------------|---------------------------------|-------------------|------------------------------------------------------------------------------------------|--------------|
+| GET    | `/system`  | Autenticada  | Retorna informações do sistema. | -                 | Informações detalhadas do sistema operacional, hardware, banco de dados, módulos e usuários | -            |
+
+## 4. Regras de autenticação e autorização
+
+- A maioria dos endpoints requer autenticação via token JWT.
+- Endpoints públicos são indicados explicitamente.
+- Controle de acesso baseado em roles e permissões.
+- MFA (Multi-Factor Authentication) suportado via TOTP, email e códigos de recuperação.
+- WebAuthn suportado para autenticação forte.
+- Refresh tokens são gerenciados via cookies HTTP-only ou no corpo da requisição.
+- Operações sensíveis (criação, atualização, deleção) requerem autenticação e permissões adequadas.
+
+## 5. Estruturas de request/response
+
+### DTOs principais do módulo AI
+
+- **ChatDTO**
+
+```ts
+{
+  message: string; // obrigatório
+  provider?: 'openai' | 'gemini'; // opcional, padrão 'openai'
+  model?: string; // opcional
+  systemPrompt?: string; // opcional
+  file_id?: number; // opcional
+}
+```
+
+- **ChatAgentDTO**
+
+```ts
+{
+  message: string; // obrigatório
+  file_id?: number; // opcional
+}
+```
+
+- **CreateAgentDTO**
+
+```ts
+{
+  slug: string; // obrigatório
+  provider?: 'openai' | 'gemini'; // opcional, padrão 'openai'
+  model?: string; // opcional
+  instructions?: string; // opcional
+}
+```
+
+- **UpdateAgentDTO**
+
+```ts
+{
+  slug?: string;
+  provider?: 'openai' | 'gemini';
+  model?: string;
+  instructions?: string;
+}
+```
+
+- **DeleteDTO**
+
+```ts
+{
+  ids: number[]; // array de IDs para deleção, mínimo 1 item
+}
+```
+
+### DTOs principais do módulo Auth
+
+- **LoginDTO**
+
+```ts
+{
+  email: string; // obrigatório, email válido
+  password: string; // obrigatório, senha forte mínima 6 caracteres
+  refreshToken?: boolean; // opcional, padrão false
+}
+```
+
+- **LoginEmailVerificationDTO**
+
+```ts
+{
+  token: string; // obrigatório
+  code: string; // obrigatório, código PIN
+}
+```
+
+- **LoginEmailVerificationResendDTO**
+
+```ts
+{
+  token: string; // obrigatório
+}
+```
+
+- **LoginWithCodeDTO**
+
+```ts
+{
+  code: string; // obrigatório
+  token: string; // obrigatório, JWT
+  methodType?: 'totp' | 'email' | 'recovery'; // opcional
+}
+```
+
+- **LoginWithRecoveryCodeDTO**
+
+```ts
+{
+  code: string; // obrigatório
+  token: string; // obrigatório, JWT
+}
+```
+
+- **ForgetDTO**
+
+```ts
+{
+  email: string; // obrigatório, email válido
+}
+```
+
+- **ResetDTO**
+
+```ts
+{
+  password: string; // obrigatório, mínimo 8 caracteres
+  code: string; // obrigatório
+}
+```
+
+## 6. Erros comuns
+
+- **400 Bad Request**
+
+  - Chave API não configurada para OpenAI ou Gemini.
+  - Slug de agente AI já existente.
+  - Código de verificação inválido ou expirado.
+  - Refresh token não fornecido.
+  - Acesso negado por credenciais inválidas.
+  - MFA não configurado ou código inválido.
+  - Tentativa de deletar itens inexistentes.
+
+- **404 Not Found**
+
+  - Agente AI não encontrado por ID ou slug.
+  - Dashboard, componente ou relação não encontrada.
+  - Desafio (challenge) para verificação não encontrado ou expirado.
+
+- **403 Forbidden**
+
+  - Acesso negado a dashboards ou recursos protegidos.
+
+## 7. Banco de dados (tabelas YAML)
+
+### ai_agent
+
+```yaml
+finalidade: Armazena agentes de inteligência artificial configurados no sistema.
+colunas:
+  - id: integer, PK, auto-increment
+  - slug: string, único, não nulo
+  - provider: enum('openai', 'gemini'), não nulo
+  - model: string, nullable
+  - instructions: string, nullable
+  - external_agent_id: string, nullable
+  - created_at: timestamp, não nulo, default NOW()
+  - updated_at: timestamp, não nulo, default NOW()
+defaults:
+  - created_at: NOW()
+  - updated_at: NOW()
+nulabilidade:
+  - model: nullable
+  - instructions: nullable
+  - external_agent_id: nullable
+integridade:
+  - slug único
+indices:
+  - id (PK)
+  - slug (único)
+enums:
+  - provider: ['openai', 'gemini']
+```
+
+### user, user_mfa, user_identifier, user_session, user_activity, role, role_user, dashboard, dashboard_component, dashboard_role, dashboard_user, dashboard_item, dashboard_component_role
+
+- Estruturas padrão para usuários, autenticação multifator, sessões, atividades, roles, dashboards e seus componentes, com relacionamentos muitos-para-muitos e suporte a internacionalização via tabelas de locale.
+
+- Campos comuns incluem IDs, slugs, timestamps de criação e atualização, e campos específicos para configurações de MFA, tokens, e layouts de dashboards.
+
+- Integridade referencial garantida via chaves estrangeiras.
+
+## 8. Regras de negócio relevantes
+
+- Agentes AI podem ser criados, atualizados e deletados, com integração direta com APIs OpenAI e Gemini.
+
+- Chat com IA suporta anexos de arquivos, com extração de texto para PDFs e arquivos de texto.
+
+- MFA obrigatório pode ser configurado, com suporte a email, TOTP e WebAuthn.
+
+- Tokens de acesso e refresh são gerenciados com segurança, incluindo cookies HTTP-only.
+
+- Dashboards são personalizados por usuário, com controle de acesso baseado em roles.
+
+- Layouts de dashboards e widgets podem ser salvos e recuperados por usuário.
+
+- Sistema coleta estatísticas de uso, sessões, emails enviados e segurança da conta.
+
+- Validações rigorosas são aplicadas via DTOs e classes de validação.
+
+## 9. Guia rápido de uso (exemplos)
+
+### Criar agente AI
+
+```http
+POST /ai/agent
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "slug": "meu-agente",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "instructions": "Seja um assistente amigável."
+}
+```
+
+Resposta:
+
+```json
+{
+  "id": 1,
+  "slug": "meu-agente",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "instructions": "Seja um assistente amigável.",
+  "external_agent_id": "abc123",
+  "created_at": "2024-06-01T12:00:00Z",
+  "updated_at": "2024-06-01T12:00:00Z"
+}
+```
+
+### Chat com agente AI
+
+```http
+POST /ai/agent/meu-agente/chat
+Authorization: Bearer <token>
+Content-Type: multipart/form-data
+
+Form-data:
+- message: "Olá, como você está?"
+- file: (arquivo opcional)
+```
+
+Resposta:
+
+```json
+{
+  "slug": "meu-agente",
+  "provider": "openai",
+  "model": "gpt-4o-mini",
+  "content": "Olá! Estou bem, obrigado por perguntar."
+}
+```
+
+### Login com email e senha
+
+```http
+POST /auth/login
+Content-Type: application/json
+
+{
+  "email": "usuario@exemplo.com",
+  "password": "senhaSegura123"
+}
+```
+
+Resposta:
+
+```json
+{
+  "accessToken": "<jwt_access_token>",
+  "refreshToken": "<jwt_refresh_token>"
+}
+```
+
+### Obter informações do sistema
+
+```http
+GET /system
+Authorization: Bearer <token>
+```
+
+Resposta (exemplo resumido):
+
+```json
+{
+  "os": {
+    "name": "Linux",
+    "platform": "linux",
+    "version": "5.15.0",
+    "architecture": "x64",
+    "uptime": 123456,
+    "cpu": {
+      "model": "Intel(R) Xeon(R)",
+      "speed": 2400,
+      "physicalCores": 4,
+      "virtualCores": 8
+    },
+    "memory": {
+      "total": 17179869184,
+      "free": 8589934592
+    },
+    "disk": [
+      {
+        "filesystem": "/dev/sda1",
+        "size": 500107862016,
+        "free": 250053931008,
+        "mountpoint": "/"
+      }
+    ]
+  },
+  "modules": [
+    {
+      "name": "@hedhog/core",
+      "version": "^1.0.0",
+      "latestVersion": "1.0.1",
+      "upToDate": false
+    }
+  ],
+  "users": {
+    "total": 100,
+    "admin": 5,
+    "active": 80,
+    "activities": []
+  },
+  "database": {
+    "connections": 10,
+    "size": 104857600,
+    "queriesPerSecond": 50
+  }
+}
+```
+
+---
+
+Este README documenta o módulo `@hed-hog/core` com base no código-fonte e definições atuais, fornecendo uma visão técnica detalhada para desenvolvedores e integradores do sistema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/core",
-  "version": "0.0.270",
+  "version": "0.0.273",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -30,12 +30,12 @@
     "sharp": "^0.34.2",
     "speakeasy": "^2.0.0",
     "uuid": "^11.1.0",
-    "@hed-hog/api-pagination": "0.0.6",
     "@hed-hog/api-prisma": "0.0.5",
+    "@hed-hog/api-pagination": "0.0.6",
     "@hed-hog/api-locale": "0.0.13",
-    "@hed-hog/api-mail": "0.0.8",
     "@hed-hog/api": "0.0.4",
-    "@hed-hog/api-types": "0.0.1"
+    "@hed-hog/api-types": "0.0.1",
+    "@hed-hog/api-mail": "0.0.8"
   },
   "exports": {
     ".": {