SDK

cloudbroker-sdk é o SDK oficial (Node.js, publicado no npm sem scope — conta npm free não permite pacote scoped). Cobre dois casos de uso: Token Intelligence (custo de IA) e Cost per Feature (custo de nuvem por trecho de código).

npm install cloudbroker-sdk

Gere sua API key em app.cloudbroker.app.br → Configurações → API Keys.

Token Intelligence — custo de IA

Envolve seu client OpenAI ou Anthropic — todas as chamadas continuam funcionando exatamente igual, o SDK só observa e registra o usage em background.

import OpenAI from "openai";
import { CloudBrokerAI } from "cloudbroker-sdk";

const openai = CloudBrokerAI.wrap(new OpenAI(), {
  apiKey:  "cb-key-xxxx",
  product: "checkout",
  team:    "mobile", // opcional
});

const res = await openai.chat.completions.create({
  model:    "gpt-4o",
  messages: [{ role: "user", content: "Olá!" }],
});

Funciona igual com Anthropic (@anthropic-ai/sdk), e com stream: true — o SDK observa os chunks conforme você consome e registra o usage ao final, sem alterar o fluxo original.

Rastreamento de deploy

openai.trackDeploy({
  repo: "myapp", branch: "main", prTitle: "feat: add new feature",
  prUrl: "https://github.com/org/myapp/pull/42", author: "john.doe",
  prNumber: 42, filesChanged: 5, linesAdded: 120, linesRemoved: 30,
});

Cost per Feature — custo de nuvem por linha de código

Envolve um client do AWS SDK v3 e, a cada .send(), estima o custo (requests + transferência) e registra um evento.

Escopo do MVP

Hoje cobre só AWS, serviços S3 e DynamoDB, região us-east-2. Armazenamento GB-mês, Azure e atribuição automática por stack-trace estão fora do escopo atual.

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { CloudBrokerCloud } from "cloudbroker-sdk";

const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: "us-east-2" }), {
  apiKey: "cb-key-xxxx", product: "checkout", team: "mobile",
});

await s3.send(new PutObjectCommand({ Bucket: "b", Key: "nf.pdf", Body: buf }), {
  cbLabel: "upload-nota-fiscal",
});

Cada chamada gera um evento com service, operation, product, team, label, requests, bytesIn/bytesOut, costUSD estimado e latencyMs.

Atribuição automática via middleware Express

Em vez de passar cbLabel em cada .send(), use o middleware — toda chamada de nuvem feita durante a requisição herda um label automaticamente via AsyncLocalStorage:

import { CloudBrokerCloud } from "cloudbroker-sdk";

app.use(CloudBrokerCloud.expressMiddleware({
  team:    (req) => (req.path.startsWith("/api/admin") ? "Plataforma" : "Produto"),
  product: (req) => req.path.split("/")[2] || "core",
  label:   (req) => `${req.method} ${req.path}`,
}));

Prioridade: cbLabel/cbProduct/cbTeam explícito no .send() > contexto do middleware > valor estático do wrapAWS > null.

Reconciliação com a fatura real

O custo estimado pelo SDK é comparado automaticamente contra o Cost Explorer da AWS — a cobertura mede quanto do custo real os trechos instrumentados explicam (estimado sempre ≤ real, nunca o inverso).

Garantias

• Fire-and-forget: se o CloudBroker estiver fora do ar, sua aplicação não é afetada
• Zero latência adicional: tracking acontece em background
• Retry automático: eventos com falha são reenviados em 30s
• Fila local: até 500 eventos em memória se o servidor estiver indisponível

MCP

O cloudbroker-mcp é um servidor MCP (Model Context Protocol) que conecta seu assistente de IA — Claude Desktop, Cursor, ChatGPT — direto aos seus dados do CloudBroker, sem abrir a console.

{
  "mcpServers": {
    "cloudbroker": {
      "command": "npx",
      "args": ["-y", "cloudbroker-mcp"],
      "env": { "CLOUDBROKER_API_KEY": "cb_live_xxx" }
    }
  }
}

Tools de leitura: get_cost_overview, list_apps, list_groups, get_forecast, get_ai_usage, get_recommendations, get_anomalies, get_saas_costs, get_daily_costs, discovery_scan.

Tools de escrita (o cliente MCP pede aprovação a cada chamada): set_budget, create_app, update_app, create_group, update_group.

A autenticação é via API key CloudBroker no header x-api-key — mesmos endpoints REST usados pela interface, sob o middleware requireAuthOrApiKey.