npm package: @libervia.xyz/sdk
Description: SDK TypeScript para integração com Libervia IDG Reference Architecture
Author: Bazari
Latest version: 1.0.0

# @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

```bash
npm install @libervia.xyz/sdk
```

## Uso Rápido

```typescript
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

```typescript
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

```typescript
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)

```typescript
// 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)

```typescript
// 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)

```typescript
// 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

```typescript
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](https://libervia.io/docs)
- [White Paper](https://libervia.io/whitepaper)
- [GitHub](https://github.com/bazari/libervia)

## Licença

Apache-2.0