1
lorenzoalberto
5 min de leitura ·

[Pitch]: Publiquei meu primeiro pacote no npm: um SDK TypeScript para a API Pública do DataJud

Publiquei meu primeiro pacote no npm: um SDK TypeScript para a API Pública do DataJud

Recentemente concluí um projeto que eu queria desenvolver há algum tempo: o DataJud SDK, um SDK TypeScript para consumir a API Pública do DataJud, mantida pelo Conselho Nacional de Justiça.

O projeto está disponível em três formatos:

A instalação pode ser feita com:

npm install @lorenzoalberto-dev/datajud-sdk

Este foi meu primeiro pacote publicado oficialmente no npm.

Mais do que criar uma abstração para a API do DataJud, meu objetivo principal foi estudar, na prática:

  • desenho de APIs públicas;
  • experiência de desenvolvimento, ou DX;
  • organização e distribuição de pacotes TypeScript;
  • modelagem de tipos;
  • tratamento consistente de erros;
  • paginação de grandes conjuntos de dados;
  • compatibilidade e estabilidade de uma interface pública;
  • automação de testes, validações e publicação.

O problema

A API Pública do DataJud permite consultar metadados de processos judiciais de diferentes tribunais brasileiros.

Ela utiliza endpoints baseados no Elasticsearch e recebe consultas no formato Query DSL. Isso oferece bastante flexibilidade, mas também transfere para quem está integrando algumas responsabilidades:

  • construir corretamente o objeto da consulta;
  • conhecer os aliases dos tribunais;
  • gerenciar paginação com search_after;
  • tratar timeouts e erros HTTP;
  • implementar novas tentativas;
  • validar números processuais;
  • manter tipos compatíveis com as respostas da API.

A proposta do SDK é reduzir essa carga sem esconder completamente os recursos oferecidos pelo DataJud.

Exemplo de uso

Uma consulta pode ser construída utilizando o QueryBuilder:

import {
  DataJudClient,
  QueryBuilder,
} from '@lorenzoalberto-dev/datajud-sdk';

const client = new DataJudClient({
  apiKey: process.env.DATAJUD_API_KEY!,
});

const query = new QueryBuilder()
  .classe(1116)
  .orgaoJulgador(13597)
  .intervaloDatas('2024-01-01', '2024-12-31')
  .build();

const response = await client.search('TJDFT', {
  query,
  source: [
    'numeroProcesso',
    'classe',
    'orgaoJulgador',
  ],
  size: 100,
});

for (const hit of response.hits.hits) {
  console.log(hit._source.numeroProcesso);
}

Também é possível percorrer resultados paginados com um AsyncIterator, sem controlar manualmente o cursor do search_after:

const query = new QueryBuilder()
  .intervaloDatas('2024-01-01', '2024-12-31')
  .build();

for await (const processo of client.iterate('TJSP', {
  query,
  source: ['numeroProcesso', '@timestamp'],
  pageSize: 500,
})) {
  console.log(processo.numeroProcesso);
}

Consulta por número processual

O SDK inclui utilitários para normalizar e validar números no padrão CNJ.

Além da validação, ele consegue identificar o segmento e o tribunal a partir do próprio número do processo:

import {
  DataJudClient,
  ProcessosService,
} from '@lorenzoalberto-dev/datajud-sdk';

const client = new DataJudClient({
  apiKey: process.env.DATAJUD_API_KEY!,
});

const processos = new ProcessosService(client);

const response = await processos.porNumero(
  '0000832-35.2018.4.01.3202',
);

Os helpers também podem ser utilizados separadamente:

import {
  isValidNumeroProcesso,
  parseNumeroProcesso,
} from '@lorenzoalberto-dev/datajud-sdk';

isValidNumeroProcesso(
  '0000832-35.2018.4.01.3202',
); // true

parseNumeroProcesso(
  '0000832-35.2018.4.01.3202',
).alias; // TRF1

Características do SDK

Atualmente, o pacote oferece:

  • API centrada em DataJudClient.search();
  • tipagem para consultas, processos e respostas;
  • Query Builder para filtros processuais comuns;
  • suporte direto à Query DSL;
  • paginação contínua com search_after;
  • consumo paginado por meio de AsyncIterator;
  • validação e normalização de números CNJ;
  • resolução automática do tribunal pelo número processual;
  • timeout configurável;
  • cancelamento com AbortSignal;
  • retry com backoff;
  • rate limiting local;
  • hierarquia consistente de erros;
  • suporte a implementação customizada de cache;
  • suporte a logger customizado;
  • zero dependências em runtime.

Um dos critérios do projeto foi manter o núcleo pequeno e evitar adicionar abstrações antes que exista uma necessidade concreta.

O que aprendi publicando meu primeiro pacote

A parte mais interessante não foi somente fazer as requisições funcionarem.

Publicar uma biblioteca exige pensar em questões que normalmente não aparecem quando o código fica restrito a uma aplicação.

A API pública vira um contrato

Renomear uma função, alterar um parâmetro ou modificar um tipo deixa de ser apenas uma refatoração interna. Essas mudanças podem quebrar projetos que dependem do pacote.

A ergonomia importa

Uma interface pode estar tecnicamente correta e ainda assim ser desagradável de usar.

Foi necessário revisar nomes, retornos, valores padrão e responsabilidades até chegar a uma API relativamente pequena.

Erros também fazem parte da API

Erros de autenticação, validação, limite de requisições e respostas HTTP não devem chegar ao consumidor como exceções genéricas e pouco previsíveis.

Por isso, o projeto expõe classes de erro próprias, como:

AuthenticationError
RateLimitError
ValidationError
DataJudError

Empacotamento é parte do produto

Também precisei estudar:

  • exports;
  • geração de declarações TypeScript;
  • arquivos incluídos no pacote;
  • versionamento semântico;
  • licença;
  • documentação;
  • validação do pacote antes da publicação;
  • integração contínua;
  • smoke tests de instalação.

São detalhes pouco visíveis para quem apenas instala uma dependência, mas influenciam diretamente a confiabilidade do pacote.

Explorador web

Além do SDK, criei uma interface web para experimentar consultas sem precisar montar um projeto local:

https://datajud-sdk.vercel.app/

O explorador não substitui o pacote. Ele funciona como uma demonstração prática e uma forma mais rápida de conhecer o formato das consultas e respostas.

Próximos passos

O projeto já atende ao escopo que defini para a primeira versão, mas ainda existem possíveis evoluções:

  • ampliar gradualmente o Query Builder;
  • melhorar a inferência dos campos retornados em _source;
  • criar mais exemplos de consultas reais;
  • expandir a cobertura de testes;
  • avaliar novos serviços de alto nível;
  • acompanhar alterações da API Pública do DataJud.

Quero evitar, entretanto, que o projeto cresça apenas para aparentar ter mais funcionalidades. A prioridade é manter uma API previsível, documentada e relativamente simples.

Feedback

Como este é meu primeiro pacote publicado no npm, feedbacks sobre arquitetura, documentação, ergonomia e tipagem são especialmente úteis.

Também tenho interesse em conhecer casos reais de uso da API do DataJud que possam ajudar a direcionar as próximas versões.

Links do projeto

O projeto é independente e não possui vínculo oficial com o Conselho Nacional de Justiça.

Carregando publicação patrocinada...