ANPD Shared Types (BETA)

Repositório central de tipos, DTOs, enums e interfaces compartilhadas para os projetos da ANPD.

⚠️ VERSÃO BETA - Esta biblioteca está em desenvolvimento ativo. Use com cautela em produção.

🚨 Migração para v0.2.0 (API Quarkus)

A versão 0.2.0 introduz breaking changes significativos para suportar a nova API Quarkus de Controladores. Se você está migrando de versões anteriores, consulte a seção de migração.

Principais Mudanças

✨ IDs agora são UUID (string) ao invés de number
✨ Campos de contato são arrays (emails[], telefones[])
✨ Novos enums: SetorEmpresarial, Esfera, Poder
✨ ControladorDto redesenhado com campos obrigatórios da API Quarkus
✨ EncarregadoDto redesenhado sem referências diretas a controlador

🎯 Visão Geral

Este pacote centraliza todos os tipos TypeScript reutilizáveis, Data Transfer Objects (DTOs), enums e interfaces utilizados nos diversos serviços e aplicações da ANPD. O objetivo é garantir padronização, reuso de código e consistência tipada em toda a stack, servindo como a fonte única da verdade para os contratos de dados.

📦 Publicado no NPM: @anpdgovbr/shared-types

🔄 Compatibilidade de APIs

Faixa de versão	Backend oficial	Observações principais
`0.1.x`	`controladores-api-nest`	IDs numéricos e campos singulares (`email`, `telefone`).
`0.2.x`	`controladores-api-quarkus`	IDs em UUID v4, contatos em arrays (`emails`, `telefones`) e enums `SetorEmpresarial`, `Esfera`, `Poder`.

As versões 0.2.x são compatíveis apenas com os contratos gerados pelo OpenAPI controladores-openapi.json (Quarkus). Consumidores ainda integrados ao backend NestJS devem permanecer em 0.1.x até finalizar a migração.

Migração Controladores Quarkus (`0.2.x`)

BaseEntity.id agora é um UUID (string) seguindo [a-f0-9-]{36}. Utilize crypto.randomUUID() para gerar IDs em testes/mocks.
Contatos de Controladores e Encarregados passam a ser arrays (EmailContatoDto[], TelefoneContatoDto[]) alinhados ao contrato OpenAPI.
Novos enums SetorEmpresarial, Esfera, Poder e TipoPessoaEnum orientam os campos obrigatórios do backend Quarkus.
DTOs atualizados:
- ControladorDto reflete os campos nomeEmpresarial, setorEmpresarial, setorId e cnaeId em UUID, além de emails/telefones.
- CnaeDto, SetorDto e SocioControladorDto utilizam UUIDs e expõem exclusionDate como string ISO.
- EncarregadoDto remove vínculos diretos com Controladores, preservando apenas os dados de contato e identificação.
BaseQueryParams.orderBy agora aceita apenas campos expostos pelo Quarkus (nomeEmpresarial, codigo, nome), evitando divergências de ordenação.

Checklist de migração para times consumidores

Atualize a dependência para @anpdgovbr/shared-types@0.2.x em backlog-dim, portais públicos e ferramentas de auditoria.
Ajuste IDs: substitua tipos numéricos (number) por string/UUID em stores, schemas e payloads.
Normalize contatos: adeque formulários e persistência para lidar com arrays de e-mails/telefones.
Reveja filtros e ordenações: garanta que orderBy, setorEmpresarial, esfera e poder estejam sincronizados com os novos enums.
Regenerar mocks: utilize crypto.randomUUID() ou fixtures equivalentes para cenários de teste.

📦 Como Usar

1. Instalação

# Com npm (fixando a versão beta)
npm install @anpdgovbr/shared-types@0.2.0-beta.0

# Com yarn
yarn add @anpdgovbr/shared-types@0.2.0-beta.0

# Com pnpm
pnpm add @anpdgovbr/shared-types@0.2.0-beta.0

2. Suporte a Múltiplos Módulos

Esta biblioteca suporta tanto CommonJS quanto ES Modules, permitindo uso flexível em diferentes ambientes:

// Import padrão (funciona em ambos os módulos)
import { UserDto, AcaoAuditoria } from "@anpdgovbr/shared-types"

// Import específico de tipos
import type {
  BaseQueryParams,
  BasePaginatedResponse,
} from "@anpdgovbr/shared-types"

// Import de utilitários (funções runtime)
import { isStatusInterno, coerceStatusInterno } from "@anpdgovbr/shared-types"

3. Importação de Tipos

Importe os tipos diretamente do pacote. O ponto de entrada principal exporta todas as entidades "core" do sistema.

import {
  UserDto,
  AcaoAuditoria,
  BaseQueryParams,
  BasePaginatedResponse
} from "@anpdgovbr/shared-types"

// Exemplo de uso em paginação
const params: BaseQueryParams = {
  page: 1,
  pageSize: 10,
  search: "termo de busca",
  orderBy: "nome",
  ascending: true
}

// Exemplo de resposta tipada
const response: BasePaginatedResponse<UserDto> = {
  data: [...],
  total: 50
}

Trabalhando com Usuários e Auditoria

import { UserDto, AuditLogDto, AcaoAuditoria } from "@anpdgovbr/shared-types"

// Definindo um usuário
const usuario: UserDto = {
  id: "uuid-123",
  email: "joao@anpd.gov.br",
  nome: "João Silva",
  perfilId: 1,
  active: true,
}

// Log de auditoria
const auditLog: AuditLogDto = {
  id: 1,
  tabela: "usuarios",
  acao: AcaoAuditoria.CREATE,
  registroId: 123,
  userId: usuario.id,
  email: usuario.email,
  // Metadados de contexto (herdados de AuditContext)
  ip: "203.0.113.10",
  userAgent: "Mozilla/5.0",
  contexto: "Cadastro inicial",
  // Identificadores de correlação / trace distribuído (opcionais)
  requestId: "req-01HQZ0X9W5K7M6N7JZ8R4XYTQ2",
  traceId: "0af7651916cd43dd8448eb211c80319c",
  spanId: "b7ad6b7169203331",
  criadoEm: new Date(),
}

Sistema de Permissões

import {
  PermissaoDto,
  PermissaoPayload,
  AcaoPermissao,
  RecursoPermissao,
} from "@anpdgovbr/shared-types"

// Criando uma permissão
const novaPermissao: PermissaoPayload = {
  perfilId: 1,
  acao: "Editar" as AcaoPermissao,
  recurso: "Processo" as RecursoPermissao,
  permitido: true,
}

// Resultado da criação
const permissaoCriada: PermissaoDto = {
  id: 10,
  acao: "Editar",
  recurso: "Processo",
  permitido: true,
  perfilId: 1,
}

Domínio RH (Cargos e Estrutura)

import type {
  Cargo,
  AllowedField,
  ALLOWED_FIELDS,
} from "@anpdgovbr/shared-types"

// Exemplo de uso dos tipos em posições de tipo
type CargoResumo = Pick<Cargo, "id" | "titulo_canonico" | "familia">

// Campos AD permitidos (array somente leitura)
const campos: ReadonlyArray<AllowedField> = ALLOWED_FIELDS

Transversal: Microsoft Graph

import type {
  GraphUser,
  GraphGroup,
  GraphPagedResponse,
} from "@anpdgovbr/shared-types"

async function listarUsuarios(): Promise<GraphPagedResponse<GraphUser>> {
  // ... sua chamada ao Graph aqui
  return { value: [], "@odata.nextLink": undefined }
}

Trabalhando com Controladores (API Quarkus - v0.2.0+)

import {
  ControladorDto,
  EmailContatoDto,
  TelefoneContatoDto,
  TipoControlador,
  SetorEmpresarial,
  Esfera,
  Poder,
  PageResponseDto,
  UUID,
} from "@anpdgovbr/shared-types"

// Criando um controlador público federal
const controlador: ControladorDto = {
  nomeEmpresarial: "Ministério da Economia",
  nomeFantasia: "ME",
  tipo: TipoControlador.PESSOA_JURIDICA,
  cpf: "12345678900", // CPF do responsável
  cnpj: "00000000000191",
  site: "https://www.gov.br/economia",
  emails: [
    { email: "contato@economia.gov.br" },
    { email: "dpo@economia.gov.br" },
  ],
  telefones: [{ codigoPais: "+55", telefone: "6132255000" }],
  politicaPrivacidadeUrl: "https://www.gov.br/economia/privacidade",
  setorEmpresarial: SetorEmpresarial.PUBLICO,
  esfera: Esfera.FEDERAL,
  poder: Poder.EXECUTIVO,
  setorId: "550e8400-e29b-41d4-a716-446655440000",
  cnaeId: "660e8400-e29b-41d4-a716-446655440000",
  active: true,
}

// Trabalhando com respostas paginadas da API Quarkus
const response: PageResponseDto<ControladorDto> = {
  data: [controlador],
  page: 0,
  pageSize: 10,
  totalElements: 1,
  totalPages: 1,
}

// Validando UUID
import { isUUID, assertUUID } from "@anpdgovbr/shared-types"

const id: UUID = "550e8400-e29b-41d4-a716-446655440000"
if (isUUID(id)) {
  console.log("UUID válido")
}

Trabalhando com Encarregados (v0.2.0+)

import {
  EncarregadoDto,
  TipoControlador,
  EmailContatoDto,
  TelefoneContatoDto,
} from "@anpdgovbr/shared-types"

// Encarregado interno (pessoa natural)
const encarregado: EncarregadoDto = {
  id: "770e8400-e29b-41d4-a716-446655440000",
  nome: "Maria Silva",
  tipo: TipoControlador.PESSOA_NATURAL,
  cpf: "12345678900",
  externo: false,
  emails: [{ email: "maria.silva@empresa.com.br" }],
  telefones: [{ codigoPais: "+55", telefone: "61999999999" }],
  active: true,
}

// Encarregado externo (empresa de consultoria)
const encarregadoExterno: EncarregadoDto = {
  nome: "DPO Consultoria LTDA",
  tipo: TipoControlador.PESSOA_JURIDICA,
  cpf: "98765432100", // CPF do responsável
  cnpj: "12345678000190",
  externo: true,
  emails: [{ email: "contato@dpoconsultoria.com.br" }],
  telefones: [{ codigoPais: "+55", telefone: "1133334444" }],
  active: true,
}

📚 Estrutura do Projeto

src/
├── base/                    # 🏗️ Interfaces base e contratos fundamentais
│   ├── base-entity.interface.ts        # Entidade base com ID
│   ├── named-entity.interface.ts       # Entidade nomeada
│   ├── soft-delete.interface.ts        # Exclusão lógica
│   ├── audit-context.interface.ts      # Contexto de auditoria
│   └── audited-entity.interface.ts     # Entidade auditável
│
├── dto/                     # 📄 Data Transfer Objects
│   ├── user.dto.ts                     # Usuário do sistema
│   ├── processo.dto.ts                 # Processos (Input/Output/Importação)
│   ├── controlador.dto.ts              # Controladores de dados
│   ├── permissao.dto.ts                # Sistema de permissões
│   └── ...                            # Outros DTOs
│
├── enums/                   # 🔢 Enumerações e tipos constantes
│   ├── acao-auditoria.enum.ts          # Ações de auditoria
│   ├── permissao.enum.ts               # Tipos de permissão
│   ├── status-interno.enum.ts          # Status internos
│   └── ...                            # Outros enums
│
├── interfaces/              # 🔌 Interfaces utilitárias
│   ├── base-query-params.interface.ts  # Parâmetros de consulta
│   ├── base-paginated-response.interface.ts # Resposta paginada
│   └── enum-data.interface.ts          # Dados enumerados
│
├── domain/                 # 🧭 Tipos de domínios específicos (ex.: RH)
│   └── rh/                 # Cargos, Estrutura Organizacional, Vocabulários RH
│
└── index.ts                 # 📥 Ponto de entrada principal

🛠️ Para Desenvolvedores

Scripts Disponíveis

# Compilar o projeto (CommonJS + ESM)
npm run build

# Modo watch para desenvolvimento
npm run watch

# Limpar arquivos de build
npm run clean

# Verificar lint
npm run lint

# Corrigir problemas de lint automaticamente
npm run lint:fix

# Formatar código
npm run format

# Verificar formatação
npm run format:check

# Verificar tipos sem gerar arquivos
npm run type-check

# Gerar documentação com Typedoc
npm run docs

# Servir documentação localmente
npm run docs:serve

📖 Documentação

A documentação completa da API é gerada automaticamente usando Typedoc a partir dos comentários TSDoc no código fonte.

Gerar e Visualizar Documentação

# Gerar documentação HTML em ./docs
npm run docs

# Servir documentação localmente para visualização interativa
npm run docs:serve

Após executar npm run docs, abra o arquivo ./docs/index.html no navegador para navegar pela documentação interativa dos tipos, interfaces, enums e DTOs disponíveis.

Adicionando Novos Tipos

Tipos Core (Transversais)
- Adicione em src/ na pasta apropriada (dto/, enums/, interfaces/, base/)
- Exporte no index.ts da pasta
- Documente usando TSDoc
Exemplo de novo DTO:

// src/dto/novo-tipo.dto.ts
import { BaseEntity } from "../base"

/**
 * Representa um novo tipo no sistema.
 *
 * @remarks
 * Descrição detalhada do propósito e uso do tipo.
 *
 * @example
 * ```typescript
 * const exemplo: NovoTipoDto = {
 *   id: 1,
 *   nome: "Exemplo"
 * }
 * ```
 */
export interface NovoTipoDto extends BaseEntity {
  nome: string
  // outras propriedades...
}

Adicione no barrel export:

// src/dto/index.ts
export { NovoTipoDto } from "./novo-tipo.dto"

⚠️ Status Beta

Esta biblioteca está atualmente em versão beta (0.1.7-beta-x). Isso significa:

✅ Funcional: Os tipos estão funcionais e podem ser usados
⚠️ Em desenvolvimento: Pode haver mudanças que quebrem compatibilidade
🧪 Testando: Estamos refinando a API e estrutura
🤝 Feedback bem-vindo: Sugestões e issues são muito apreciados

Para Desenvolvedores

Desenvolvimento: Fique à vontade para usar e testar
Produção: Use com cautela e fixe a versão específica
Atualizações: Acompanhe o CHANGELOG para mudanças importantes

🤝 Manutenção e Contribuição

Padrões de Código

📝 Documentação: Todos os novos tipos devem ser documentados utilizando o padrão TSDoc.
🎯 Novos Tipos:
- Se o tipo for transversal e aplicável a múltiplos domínios, adicione-o em src/.
- Se o tipo for específico de um contexto de negócio, crie ou utilize a pasta do domínio correspondente (futura implementação).
🔧 Consistência: Mantenha a padronização de nomenclatura e estrutura de arquivos.

Versionamento

Este projeto segue o Semantic Versioning:

MAJOR: Mudanças que quebram compatibilidade
MINOR: Novas funcionalidades mantendo compatibilidade
PATCH: Correções de bugs mantendo compatibilidade
BETA: Versões de desenvolvimento (ex: 0.1.7-beta)

Publicação

Para publicar uma nova versão beta:

# 1. Atualizar versão no package.json para X.Y.Z-beta
npm version prerelease --preid=beta

# 2. O script prepublishOnly irá rodar automaticamente:
#    - build, lint e format:check

# 3. Publicar no NPM com tag beta
npm publish --tag beta

Para publicar versão estável:

# 1. Atualizar versão no package.json (remover -beta)
npm version patch|minor|major

# 2. Publicar no NPM
npm publish

📖 Guia de Migração (v0.1.x → v0.2.0)

Breaking Changes

A versão 0.2.0 introduz mudanças significativas para suportar a nova API Quarkus de Controladores. Este guia ajudará você a migrar seu código.

1. IDs agora são UUID (string)

Antes (v0.1.x):

interface BaseEntity {
  id: number
}

const controlador: ControladorDto = {
  id: 123,
  setorId: 456,
  cnaeId: 789,
  // ...
}

Depois (v0.2.0):

import { UUID } from "@anpdgovbr/shared-types"

interface BaseEntity {
  id: UUID // string
}

const controlador: ControladorDto = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  setorId: "660e8400-e29b-41d4-a716-446655440001",
  cnaeId: "770e8400-e29b-41d4-a716-446655440002",
  // ...
}

Ações necessárias:

Atualize todos os campos id para aceitar string ao invés de number
Use crypto.randomUUID() para gerar novos IDs
Atualize queries de banco de dados e comparações de ID
Use isUUID() para validar IDs recebidos de entrada externa

2. ControladorDto: Campos Renomeados e Reestruturados

Antes (v0.1.x):

const controlador: ControladorDto = {
  id: 123,
  nome: "Empresa ABC",
  email: "contato@empresa.com",
  telefone: "(61) 99999-9999",
  setorId: 1,
  cnaeId: 2,
  grupoEconomicoId: 3,
}

Depois (v0.2.0):

const controlador: ControladorDto = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  nomeEmpresarial: "Empresa ABC Ltda", // nome → nomeEmpresarial
  nomeFantasia: "Empresa ABC",
  tipo: TipoControlador.PESSOA_JURIDICA,
  cpf: "12345678900", // obrigatório
  cnpj: "12345678000190",
  site: "https://empresa.com",
  emails: [
    // email → emails (array)
    { email: "contato@empresa.com" },
  ],
  telefones: [
    // telefone → telefones (array)
    { codigoPais: "+55", telefone: "61999999999" },
  ],
  politicaPrivacidadeUrl: "https://empresa.com/privacidade",
  setorEmpresarial: SetorEmpresarial.PRIVADO,
  setorId: "660e8400-e29b-41d4-a716-446655440001",
  cnaeId: "770e8400-e29b-41d4-a716-446655440002",
  // grupoEconomicoId removido
  active: true,
}

Ações necessárias:

Renomeie nome para nomeEmpresarial
Converta email string para emails: EmailContatoDto[]
Converta telefone string para telefones: TelefoneContatoDto[]
Adicione campos obrigatórios: cpf, site, politicaPrivacidadeUrl, setorEmpresarial
Remova referências a grupoEconomicoId
Para controladores públicos, adicione esfera e poder

3. EncarregadoDto: Redesenhado

Antes (v0.1.x):

const encarregado: EncarregadoDto = {
  id: 123,
  nome: "Maria Silva",
  email: "maria@empresa.com",
  telefone: "(61) 99999-9999",
  externo: false,
  controladorId: 456,
}

Depois (v0.2.0):

const encarregado: EncarregadoDto = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  nome: "Maria Silva",
  tipo: TipoControlador.PESSOA_NATURAL,
  cpf: "12345678900",
  externo: false,
  emails: [{ email: "maria@empresa.com" }],
  telefones: [{ codigoPais: "+55", telefone: "61999999999" }],
  active: true,
  // controladorId removido
}

Ações necessárias:

Converta email para emails: EmailContatoDto[]
Converta telefone para telefones: TelefoneContatoDto[]
Adicione campo tipo (TipoControlador)
Adicione campo cpf obrigatório
Remova controladorId e controladorEmpresaExternaId
O relacionamento encarregado-controlador agora é gerenciado por endpoints específicos

4. CnaeDto e SetorDto: Campos Atualizados

Antes (v0.1.x):

const cnae: CnaeDto = {
  id: 123,
  name: "Comércio varejista",
  code: "47.89-0-99",
}

Depois (v0.2.0):

const cnae: CnaeDto = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  nome: "Comércio varejista", // name → nome
  codigo: "47.89-0-99", // code → codigo
  active: true,
  exclusionDate: null,
}

Ações necessárias:

Use nome ao invés de name (ou use alias deprecado temporariamente)
Use codigo ao invés de code (ou use alias deprecado temporariamente)
Os aliases name e code serão removidos na v1.0.0

5. SoftDelete: Aceita Datas como String

Antes (v0.1.x):

interface SoftDelete {
  active: boolean
  exclusionDate?: Date | null
}

Depois (v0.2.0):

interface SoftDelete {
  active: boolean
  exclusionDate?: Date | string | null // aceita ISO 8601 string
}

Ações necessárias:

APIs agora retornam exclusionDate como string ISO 8601
Converta para Date no cliente se necessário: new Date(exclusionDate)

6. Novos Tipos e Enums

import {
  SetorEmpresarial,
  Esfera,
  Poder,
  EmailContatoDto,
  TelefoneContatoDto,
  PageResponseDto,
  ControladoresFiltroDto,
  UUID,
  isUUID,
} from "@anpdgovbr/shared-types"

// Novos enums para classificação de controladores públicos
const setor = SetorEmpresarial.PUBLICO
const esfera = Esfera.FEDERAL
const poder = Poder.EXECUTIVO

// Novo formato de resposta paginada da API Quarkus
const response: PageResponseDto<ControladorDto> = {
  data: [],
  page: 0,
  pageSize: 10,
  totalElements: 0,
  totalPages: 0,
}

Checklist de Migração

Compatibilidade entre APIs

Funcionalidade	API NestJS (v0.1.x)	API Quarkus (v0.2.0)
ID Type	`number`	`UUID` (string)
Email/Telefone	String único	Array de objetos
ControladorDto.nome	✅	❌ → nomeEmpresarial
SetorEmpresarial enum	❌	✅
Esfera/Poder enums	❌	✅
grupoEconomicoId	✅	❌
EncarregadoDto.controladorId	✅	❌
PageResponseDto	❌	✅

📞 Suporte

Issues: GitHub Issues
Documentação: Este README e comentários TSDoc no código
Equipe: DDSS/CGTI/ANPD

💻 Projeto mantido pela equipe DDSS/CGTI/ANPD.

📄 Licença: MIT

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.changeset		.changeset
.github/workflows		.github/workflows
.vscode		.vscode
doc		doc
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.ncurc.json		.ncurc.json
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.cjs		jest.config.cjs
package.json		package.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json
tsconfig.test.json		tsconfig.test.json
typedoc.json		typedoc.json

anpdgovbr/shared-types

Folders and files

Latest commit

History

Repository files navigation

ANPD Shared Types (BETA)

🚨 Migração para v0.2.0 (API Quarkus)

Principais Mudanças

🎯 Visão Geral

🔄 Compatibilidade de APIs

Migração Controladores Quarkus (0.2.x)

Checklist de migração para times consumidores

📦 Como Usar

1. Instalação

2. Suporte a Múltiplos Módulos

3. Importação de Tipos

Trabalhando com Usuários e Auditoria

Sistema de Permissões

Domínio RH (Cargos e Estrutura)

Transversal: Microsoft Graph

Trabalhando com Controladores (API Quarkus - v0.2.0+)

Trabalhando com Encarregados (v0.2.0+)

📚 Estrutura do Projeto

🛠️ Para Desenvolvedores

Scripts Disponíveis

📖 Documentação

Gerar e Visualizar Documentação

Adicionando Novos Tipos

⚠️ Status Beta

Para Desenvolvedores

🤝 Manutenção e Contribuição

Padrões de Código

Versionamento

Publicação

📖 Guia de Migração (v0.1.x → v0.2.0)

Breaking Changes

1. IDs agora são UUID (string)

2. ControladorDto: Campos Renomeados e Reestruturados

3. EncarregadoDto: Redesenhado

4. CnaeDto e SetorDto: Campos Atualizados

5. SoftDelete: Aceita Datas como String

6. Novos Tipos e Enums

Checklist de Migração

Compatibilidade entre APIs

📞 Suporte

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Contributors 4

Uh oh!

Languages

Migração Controladores Quarkus (`0.2.x`)