@anpdgovbr/shared-types
Advanced tools
Biblioteca central de tipos TypeScript compartilhados para os projetos da ANPD (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.
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.
numberemails[], telefones[])SetorEmpresarial, Esfera, PoderEste 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
| 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.xsão compatíveis apenas com os contratos gerados pelo OpenAPIcontroladores-openapi.json(Quarkus). Consumidores ainda integrados ao backend NestJS devem permanecer em0.1.xaté finalizar a migração.
0.2.x)BaseEntity.id agora é um UUID (string) seguindo [a-f0-9-]{36}. Utilize crypto.randomUUID() para gerar IDs em testes/mocks.EmailContatoDto[], TelefoneContatoDto[]) alinhados ao contrato OpenAPI.SetorEmpresarial, Esfera, Poder e TipoPessoaEnum orientam os campos obrigatórios do backend Quarkus.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.@anpdgovbr/shared-types@0.2.x em backlog-dim, portais públicos e ferramentas de auditoria.number) por string/UUID em stores, schemas e payloads.orderBy, setorEmpresarial, esfera e poder estejam sincronizados com os novos enums.crypto.randomUUID() ou fixtures equivalentes para cenários de teste.# 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
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"
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
}
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(),
}
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,
}
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
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 }
}
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")
}
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,
}
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
# 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
A documentação completa da API é gerada automaticamente usando Typedoc a partir dos comentários TSDoc no código fonte.
# 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.
Tipos Core (Transversais)
src/ na pasta apropriada (dto/, enums/, interfaces/, base/)index.ts da pastaExemplo 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...
}
// src/dto/index.ts
export { NovoTipoDto } from "./novo-tipo.dto"
Esta biblioteca está atualmente em versão beta (0.1.7-beta-x). Isso significa:
src/.Este projeto segue o Semantic Versioning:
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
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.
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:
id para aceitar string ao invés de numbercrypto.randomUUID() para gerar novos IDsisUUID() para validar IDs recebidos de entrada externaAntes (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:
nome para nomeEmpresarialemail string para emails: EmailContatoDto[]telefone string para telefones: TelefoneContatoDto[]cpf, site, politicaPrivacidadeUrl, setorEmpresarialgrupoEconomicoIdesfera e poderAntes (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:
email para emails: EmailContatoDto[]telefone para telefones: TelefoneContatoDto[]tipo (TipoControlador)cpf obrigatóriocontroladorId e controladorEmpresaExternaIdAntes (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:
nome ao invés de name (ou use alias deprecado temporariamente)codigo ao invés de code (ou use alias deprecado temporariamente)name e code serão removidos na v1.0.0Antes (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:
exclusionDate como string ISO 8601Date no cliente se necessário: new Date(exclusionDate)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,
}
@anpdgovbr/shared-types@^0.2.0id de number para UUID (string)ControladorDto com novos camposemails[], telefones[])grupoEconomicoId de controladoresEncarregadoDto removendo controladorIdBasePaginatedResponse para PageResponseDto onde apropriadoControladoresFiltroDto| 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 | ❌ | ✅ |
💻 Projeto mantido pela equipe DDSS/CGTI/ANPD.
📄 Licença: MIT
FAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.