@cargolift-cdi/lib-repositories

Biblioteca de repositórios TypeORM para acesso a dados do ecossistema Middleware Cargolift em aplicações NestJS.

📌 Objetivo

Este repositório centraliza repositórios de acesso a dados para domínios do middleware (integração, logs, webhook, metadados e diagnóstico), promovendo consistência de implementação, redução de duplicidade e padronização de consultas.

No contexto do middleware, a lib oferece uma base reutilizável para persistência com foco em rastreabilidade, resiliência e manutenibilidade.

Público-alvo: Desenvolvedores de serviços NestJS que utilizam TypeORM no monorepo Middleware.

✨ Funcionalidades

• Repositórios de integração: agentes, entidades, rotas inbound/outbound, credenciais, endpoints e snapshots de saída.
• Repositórios de log: tracking de integração e logs de roteamento/MDM.
• Repositório de webhook: subscriptions com suporte a busca por evento com wildcard.
• Repositórios compartilhados: trilha de auditoria (AuditTrail) e entidade dinâmica (EntityDynamic).
• Diagnóstico de latência: acesso a dados de diagnóstico operacional.
• Classificação de erros de banco: utilitário para classificar falhas como transitórias ou fatais.

Diferenciais técnicos:

• Integração direta com @nestjs/typeorm.
• API orientada a serviços (@Injectable) pronta para injeção por módulo.
• Classificação explícita de erros SQLSTATE e erros de rede para estratégias de retry.

🔍 Detalhamento

Repositórios de Integração

A biblioteca expõe serviços para operações de leitura e persistência em entidades do domínio de integração. Exemplo: MiddlewareAgentRepository com buscas por agent, apiClientId e listagem de ativos.

Exemplo de uso

import { Injectable } from "@nestjs/common";
import { MiddlewareAgentRepository } from "@cargolift-cdi/lib-repositories";

@Injectable()
export class AgentService {
  constructor(private readonly agentRepo: MiddlewareAgentRepository) {}

  async getActiveAgent(agent: string) {
    return this.agentRepo.get(agent);
  }

  async listActiveAgents() {
    return this.agentRepo.getAllActive();
  }
}

Parâmetros:

• get(agent): identificador do agente.
• getByApiClientId(apiClientId): client id de autenticação da integração.

Retorno:

• Instância da entidade encontrada ou null.

Auditoria e Metadados Dinâmicos

AuditTrailRepository permite registrar alterações com correlação e consultar histórico por recordId ou correlationId, incluindo suporte a transações com QueryRunner.

Exemplo de uso

import { Injectable } from "@nestjs/common";
import { AuditTrailRepository } from "@cargolift-cdi/lib-repositories";

@Injectable()
export class AuditService {
  constructor(private readonly auditTrailRepo: AuditTrailRepository) {}

  async registerUpdate(correlationId: string, recordId: string) {
    await this.auditTrailRepo.register({
      entity: "customer",
      operation: "update",
      correlationId,
      recordId,
      changes: { status: { from: "inactive", to: "active" } },
    });
  }
}

Parâmetros:

• register(input): dados de auditoria da operação.
• registerWithQueryRunner(queryRunner, data): auditoria dentro da mesma transação de negócio.

Retorno:

• register: Promise<AuditTrail | null>.
• Consultas: listas de registros ordenados por data de alteração.

Webhook e Classificação de Erros

WebhookSubscriptionRepository oferece busca de assinaturas ativas por evento (entidade.ação, wildcard por entidade e wildcard global). DataBaseErrorClassifier classifica erros de persistência em TRANSIENT ou FATAL.

Exemplo de uso

import {
  WebhookSubscriptionRepository,
  DataBaseErrorClassifier,
  DatabaseErrorType,
} from "@cargolift-cdi/lib-repositories";

async function processWebhook(
  repo: WebhookSubscriptionRepository,
  entity: string,
  action: string,
) {
  try {
    const subscriptions = await repo.findActiveByEvent(entity, action);
    return subscriptions;
  } catch (error) {
    const classified = DataBaseErrorClassifier.classify(error);

    if (classified.type === DatabaseErrorType.TRANSIENT) {
      // Aplicar retry/backoff
    }

    throw error;
  }
}

Parâmetros:

• findActiveByEvent(entity, action): combinações com match exato e wildcards.
• classify(err): erro desconhecido para classificação.

Retorno:

• Lista de subscriptions ativas.
• Objeto de classificação com tipo, código e mensagem.

🛠 Tecnologias e Dependências

Dependências internas:

• @cargolift-cdi/types

🚀 Instalação

Pré-requisitos

• Node.js: >= 18
• pnpm: recomendado para uso em workspace
• DataSources TypeORM configurados na aplicação consumidora

Passos de instalação

1. Instale dependências do monorepo:

pnpm install

2. Build da biblioteca:

pnpm --filter @cargolift-cdi/lib-repositories build

Variáveis de ambiente

A biblioteca não exige variáveis de ambiente próprias, mas depende da configuração de conexão dos DataSources da aplicação consumidora.

💡 Como Usar

Quickstart

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { MiddlewareAgent } from "@cargolift-cdi/types";
import { MiddlewareAgentRepository } from "@cargolift-cdi/lib-repositories";

@Module({
  imports: [TypeOrmModule.forFeature([MiddlewareAgent], "middleware")],
  providers: [MiddlewareAgentRepository],
  exports: [MiddlewareAgentRepository],
})
export class IntegrationRepositoriesModule {}

Casos de uso avançados

• Trilha de auditoria transacional: usar registerWithQueryRunner para gravar auditoria no mesmo commit de negócio.
• Resiliência em persistência: aplicar DataBaseErrorClassifier para separar erros reprocessáveis de falhas fatais.
• Webhook com wildcard: usar findActiveByEvent para rotear eventos por assinatura dinâmica.

📁 Estrutura do Projeto

.
├── src/
│   ├── index.ts
│   ├── diagnostic/
│   ├── middleware/
│   │   ├── integration/
│   │   ├── log/
│   │   ├── shared/
│   │   └── webhook/
│   └── util/
├── package.json
├── tsconfig.json
└── README.md

• src/middleware/integration/: repositórios de agentes, rotas e snapshots.
• src/middleware/log/: persistência de logs e tracking de integrações.
• src/middleware/shared/: repositórios compartilhados (auditoria e entidades dinâmicas).
• src/middleware/webhook/: subscriptions de webhook.
• src/diagnostic/: consultas operacionais de diagnóstico.
• src/util/: utilitários de tratamento/classificação de erros.

🧪 Testes e Qualidade

No momento, o pacote possui fluxo principal de build por TypeScript.

pnpm --filter @cargolift-cdi/lib-repositories build

🤝 Contribuindo

Padrão de branches:

• main: branch principal.
• feature/*: novas funcionalidades.
• bugfix/*: correções.

Padrão de commits:

• Conventional Commits.
• Exemplos:
  • feat(repositories): adiciona busca por agentId em webhook
  • fix(repositories): corrige classificação de erro SQLSTATE

Processo de PR:

1. Criar branch a partir de main.
2. Implementar alteração mantendo compatibilidade dos serviços exportados.
3. Executar build da lib.
4. Abrir PR com descrição técnica e impacto.

📄 Licença

Este projeto é distribuído sob a licença MIT.