@libervia.xyz/sdk

SDK TypeScript para integração com a Libervia IDG Reference Architecture - o Cérebro Institucional para governança de decisões automatizadas.

Instalação

npm install @libervia.xyz/sdk

Uso Rápido

import { createLiberviaClient } from '@libervia.xyz/sdk';

// Criar cliente
const client = createLiberviaClient({
  baseUrl: 'http://localhost:3000',
  token: 'your-token',
  tenantId: 'acme' // Opcional para admin, obrigatório para APIs públicas
});

// Health check
const health = await client.health.check();
console.log(health.status); // 'ok'

// Criar decisão (fluxo principal)
const decisao = await client.public.criarDecisao({
  situacao: {
    dominio: 'financeiro',
    contexto: 'Aprovação de crédito',
    objetivo: 'Decidir sobre concessão de crédito',
    incertezas: ['capacidade de pagamento', 'histórico do cliente'],
    alternativas: [
      { descricao: 'Aprovar', riscos_associados: ['inadimplência'] },
      { descricao: 'Negar', riscos_associados: ['perda de cliente'] }
    ],
    riscos: [
      { descricao: 'Inadimplência', tipo: 'financeiro', reversibilidade: 'parcial' }
    ],
    urgencia: 'media',
    capacidade_absorcao: 'alta',
    consequencia_relevante: 'impacto financeiro',
    possibilidade_aprendizado: true,
    caso_uso_declarado: 1
  },
  protocolo: {
    criterios_minimos: ['score >= 700', 'renda comprovada'],
    riscos_considerados: ['inadimplência'],
    limites_definidos: [
      { tipo: 'valor_maximo', valor: '50000', descricao: 'Limite de crédito' }
    ],
    perfil_risco: 'moderado',
    alternativas_avaliadas: ['Aprovar', 'Negar'],
    alternativa_escolhida: 'Aprovar'
  }
});

console.log('Contrato emitido:', decisao.contrato.id);

Configuração

interface LiberviaClientOptions {
  /** URL base da API (ex: http://localhost:3000) */
  baseUrl: string;

  /** Token de autenticação */
  token: string;

  /** ID do tenant (obrigatório para APIs públicas) */
  tenantId?: string;

  /** Timeout em ms (default: 30000) */
  timeout?: number;

  /** Headers customizados */
  customHeaders?: Record<string, string>;
}

APIs Disponíveis

Health

const health = await client.health.check();     // Liveness
const ready = await client.health.ready();      // Readiness
const metrics = await client.health.metrics();  // Métricas

Admin (requer global_admin)

// Tenants
const tenants = await client.admin.listTenants();
const tenant = await client.admin.createTenant({ id: 'acme', name: 'ACME Corp' });
await client.admin.suspendTenant('acme');
await client.admin.resumeTenant('acme');

// Keys
const keys = await client.admin.listKeys('acme');
const newKey = await client.admin.createKey('acme', { role: 'tenant_admin' });
await client.admin.revokeKey('acme', newKey.keyId);

// Audit
const verify = await client.admin.verifyAudit('acme');
const events = await client.admin.listEvents('acme');

Query (requer tenant_admin ou global_admin)

// Dashboard do tenant
const dashboard = await client.query.getDashboard('acme');

// Mandatos
const mandates = await client.query.listMandates('acme');

// Casos de revisão
const reviews = await client.query.listReviews('acme');

// Consequências
const consequences = await client.query.listConsequences('acme');

Public (requer token público + tenantId)

// Criar decisão
const decisao = await client.public.criarDecisao(input);

// Consultar episódio
const episodio = await client.public.getEpisodio(decisao.episodio_id);

// Encerrar episódio
await client.public.encerrarEpisodio(episodio.episodio_id);

// Listar eventos
const eventos = await client.public.listarEventos({ limit: 50 });

Tratamento de Erros

import {
  LiberviaError,
  UnauthorizedError,
  ForbiddenError,
  NotFoundError,
  TenantConflictError
} from '@libervia.xyz/sdk';

try {
  await client.admin.getTenant('nonexistent');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Tenant não encontrado');
    console.log('Request ID:', error.requestId);
  } else if (error instanceof UnauthorizedError) {
    console.log('Token inválido ou ausente');
  } else if (error instanceof ForbiddenError) {
    console.log('Permissão insuficiente');
  } else if (error instanceof LiberviaError) {
    console.log(`Erro ${error.status}: ${error.message}`);
  }
}

Roles de Autenticação

| Role | Descrição | Acesso | |------|-----------|--------| | global_admin | Administrador global | Todas as APIs | | tenant_admin | Administrador do tenant | Query + Audit do próprio tenant | | public | API cognitiva | Criar decisões, consultar episódios |

Requisitos

• Node.js >= 18.0.0
• TypeScript >= 5.0 (recomendado)

Links

• Documentação
• White Paper
• GitHub

Licença

Apache-2.0