Viawb | MCP Gateway para ERPs

v0.3.2 — estávelnpm: viawbNode ≥ 18TypeScript 5+

Instalação

Instale o SDK via seu gerenciador de pacotes preferido.

Terminal
$ npm install viawb

Inicialização

Importe e instancie o cliente com sua chave de acesso. A API key pode ser passada diretamente ou via variável de ambiente VIAWB_API_KEY.

TypeScript / ESM
import { ViaWBClient } from "viawb";

const client = new ViaWBClient({
  apiKey: "vwb_sk_live_xxxxxxxxxxxxxxxxxxxx",
  // ou: apiKey: process.env.VIAWB_API_KEY
});

CommonJS
const { ViaWBClient } = require("viawb");

client.tools

Interaja com as ferramentas MCP disponíveis para sua chave de acesso.

client.tools.list()→ Promise<Tool[]>

Retorna a lista de ferramentas MCP disponíveis para a chave autenticada.

TypeScript
const tools = await client.tools.list();
console.log(tools.map((t) => t.name));
// → ["erp.pedidos.get", "erp.clientes.get", ...]

client.tools.call(name, args, opts?)→ Promise<ToolResult>

Executa uma ferramenta MCP com os argumentos fornecidos. A permissão é verificada antes da execução.

TypeScript
const result = await client.tools.call(
  "erp.pedidos.get",
  { pedido_id: "4421" },
  { agentId: "crm-bot-v2" }
);
console.log(result.content); // dados do pedido

client.audit

Acesse e filtre o log de auditoria de chamadas realizadas pelo gateway.

client.audit.list(filters?)→ Promise<AuditPage>

Lista entradas do log com suporte a filtros e paginação automática.

TypeScript
const page = await client.audit.list({
  agentId: "crm-bot-v2",
  status: "deny",
  from: "2026-06-01T00:00:00Z",
  limit: 50,
});

for (const entry of page.entries) {
  console.log(entry.tool, entry.decision, entry.timestamp);
}

client.audit.get(id)→ Promise<AuditEntry>

Busca o registro completo de uma entrada de log específica por ID.

TypeScript
const entry = await client.audit.get("log_01j9xkp...");

client.keys

Crie, liste e revogue chaves de acesso MCP programaticamente.

O valor secreto da chave (key.secret) é retornado somente na criação. Armazene-o imediatamente em um local seguro.

TypeScript
// Criar chave
const key = await client.keys.create({
  name: "bot-crm-producao",
  role: "reader-comercial",
});
console.log(key.secret); // salve agora!

// Listar chaves
const keys = await client.keys.list();

// Revogar chave
await client.keys.revoke("key_01j9...");

client.webhooks

Receba eventos de auditoria e alertas de anomalia em tempo real via webhook. O SDK inclui validação de assinatura e tipos para cada evento.

Configure a URL do webhook e o segredo de assinatura no dashboard em Configurações → Webhooks.

TypeScript — Express handler
import { ViaWBWebhook } from "viawb/webhooks";

app.post("/webhooks/viawb", (req, res) => {
  const event = ViaWBWebhook.parse({
    payload: req.body,
    signature: req.headers["x-viawb-signature"],
    secret: process.env.VIAWB_WEBHOOK_SECRET,
  });

  if (event.type === "audit.anomaly_detected") {
    // alertar equipe de ops
  }
  res.json({ received: true });
});"

Erros e tipos

O SDK lança erros tipados para facilitar o tratamento de exceções específicas.

TypeScript
import { ViaWBError, PermissionDeniedError } from "viawb";

try {
  await client.tools.call("erp.pedidos.delete", {});
} catch (err) {
  if (err instanceof PermissionDeniedError) {
    // 403 — papel não tem escopo DELETE
    console.error(err.message, err.requestId);
  }
}

Node.js SDK