cloudbroker-sdk 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to npm
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'package.json'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,118 @@
+# cloudbroker-sdk
+
+Token Intelligence & Operational Financial Intelligence para Node.js.
+
+## Instalação
+
+```bash
+npm install cloudbroker-sdk
+```
+
+## Uso com OpenAI
+
+```js
+import OpenAI from "openai";
+import { CloudBrokerAI } from "cloudbroker-sdk";
+
+const openai = CloudBrokerAI.wrap(new OpenAI(), {
+  apiKey:  "cb-key-xxxx",   // sua chave CloudBroker
+  product: "checkout",       // nome do produto
+  team:    "mobile",         // nome do squad (opcional)
+});
+
+// Todas as chamadas seguem iguais — nada muda
+const res = await openai.chat.completions.create({
+  model:    "gpt-4o",
+  messages: [{ role: "user", content: "Olá!" }],
+});
+```
+
+## Uso com Anthropic
+
+```js
+import Anthropic from "@anthropic-ai/sdk";
+import { CloudBrokerAI } from "cloudbroker-sdk";
+
+const anthropic = CloudBrokerAI.wrap(new Anthropic(), {
+  apiKey:  "cb-key-xxxx",
+  product: "checkout",
+  team:    "mobile",
+});
+
+const res = await anthropic.messages.create({
+  model:      "claude-sonnet-4-6",
+  max_tokens: 1024,
+  messages:   [{ role: "user", content: "Olá!" }],
+});
+```
+
+## Streaming
+
+Chamadas com `stream: true` também são rastreadas — o SDK observa os chunks
+conforme você os consome e registra o `usage` ao final, sem alterar o fluxo:
+
+```js
+const stream = await openai.chat.completions.create({
+  model:    "gpt-4o",
+  stream:   true,
+  messages: [{ role: "user", content: "Olá!" }],
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content || "");
+}
+// tokens/custo são registrados automaticamente quando o stream termina
+```
+
+Para OpenAI, o SDK injeta `stream_options: { include_usage: true }` para receber
+o `usage` no chunk final. Para Anthropic, o `usage` vem dos eventos
+`message_start` / `message_delta`. O objeto de stream original é preservado
+(`.tee()`, `.controller`, etc.).
+
+## Rastreamento de Deploy
+
+```js
+import { CloudBrokerAI } from "cloudbroker-sdk";
+
+// Opção 1: Via wrapper (se você está usando OpenAI/Anthropic)
+const openai = CloudBrokerAI.wrap(new OpenAI(), {
+  apiKey: "cb-key-xxxx",
+  product: "checkout",
+});
+
+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,
+});
+
+// Opção 2: Direto (sem OpenAI/Anthropic)
+CloudBrokerAI.trackDeploy("cb-key-xxxx", {
+  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,
+});
+```
+
+## Garantias
+
+- **Fire-and-forget**: se o CloudBroker estiver fora, sua aplicação não é afetada
+- **Zero latência adicional**: o 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
+
+## API Key CloudBroker
+
+Gere sua chave em `app.cloudbroker.app.br` → Configurações → API Keys.

package/apply_backend.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+set -e
+
+BACKEND="$HOME/Downloads/cloudbroker-backend-repo"
+SDK_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+echo "📂 Copiando patches para o backend..."
+cp "$SDK_DIR/patch_backend.py" "$BACKEND/"
+cp "$SDK_DIR/patch_db.py"      "$BACKEND/"
+
+echo ""
+echo "🔧 Patch backend — server.js (AI Gateway endpoints)..."
+cd "$BACKEND"
+python3 patch_backend.py
+
+echo ""
+echo "🔧 Patch db — db.js (putAiEvent, listAiEvents, getUserByApiKey)..."
+python3 patch_db.py
+
+echo ""
+echo "🔍 Verificando..."
+grep -n "ai/events\|ai/gateway\|putAiEvent\|listAiEvents\|getUserByApiKey" server.js db.js | head -15
+
+echo ""
+echo "🚀 Deploy backend..."
+git add server.js db.js
+git commit -m "feat: AI Gateway — endpoint /api/ai/events e /api/ai/gateway/usage para SDK"
+git push
+
+echo "✅ Backend pronto!"

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "cloudbroker-sdk",
+  "version": "0.1.0",
+  "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
+  "main": "src/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node src/test.js"
+  },
+  "keywords": ["cloudbroker", "finops", "token-intelligence", "openai", "anthropic"],
+  "license": "MIT",
+  "dependencies": {}
+}

package/patch_backend.py

@@ -0,0 +1,138 @@
+import sys
+
+with open("server.js", "r") as f:
+    content = f.read()
+
+# Adicionar tabela cb-ai-events no db.js via server.js não é possível diretamente
+# Vamos adicionar os endpoints no server.js antes do app.listen
+
+OLD = """app.post("/api/chat", requireAuth, async (req, res) => {"""
+
+NEW = """// ─── AI GATEWAY — recebe eventos do SDK ──────────────────────────────────────
+app.post("/api/ai/events", async (req, res) => {
+  try {
+    const cbKey = req.headers["x-cloudbroker-key"];
+    if (!cbKey) return res.status(401).json({ error: "x-cloudbroker-key obrigatório." });
+
+    // Valida key e busca usuário
+    const { getUserByApiKey } = await import("./db.js");
+    const user = await getUserByApiKey(cbKey).catch(() => null);
+    if (!user) return res.status(401).json({ error: "API key inválida." });
+
+    const { events = [] } = req.body;
+    if (!Array.isArray(events) || events.length === 0)
+      return res.json({ ok: true, received: 0 });
+
+    const { putAiEvent } = await import("./db.js");
+    const userId = user.userId || user.email;
+    const now    = new Date().toISOString();
+
+    await Promise.all(events.map(ev => putAiEvent({
+      userId,
+      eventId:       `${Date.now()}-${Math.random().toString(36).slice(2,8)}`,
+      provider:      ev.provider      || "unknown",
+      model:         ev.model         || "unknown",
+      product:       ev.product       || null,
+      team:          ev.team          || null,
+      inputTokens:   ev.inputTokens   || 0,
+      outputTokens:  ev.outputTokens  || 0,
+      totalTokens:   ev.totalTokens   || 0,
+      costUSD:       ev.costUSD       || 0,
+      latencyMs:     ev.latencyMs     || 0,
+      endpoint:      ev.endpoint      || null,
+      sdkVersion:    ev.sdkVersion    || null,
+      createdAt:     ev.sentAt        || now,
+    })));
+
+    return res.json({ ok: true, received: events.length });
+  } catch (err) {
+    console.warn("ai/events:", err.message);
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+// ─── AI GATEWAY — usage agregado por produto/squad/modelo ────────────────────
+app.get("/api/ai/gateway/usage", requireAuth, async (req, res) => {
+  try {
+    const { listAiEvents } = await import("./db.js");
+    const userId = req.user.sub || req.user.email;
+    const days   = parseInt(req.query.days || 30);
+    const events = await listAiEvents(userId, days);
+
+    // Agrupa por provider + modelo
+    const byModel = {};
+    const byProduct = {};
+    const dailyMap  = {};
+
+    for (const ev of events) {
+      // Por modelo
+      const mk = `${ev.provider}::${ev.model}`;
+      if (!byModel[mk]) byModel[mk] = { provider: ev.provider, model: ev.model, inputTokens: 0, outputTokens: 0, totalTokens: 0, costUSD: 0, calls: 0 };
+      byModel[mk].inputTokens  += ev.inputTokens  || 0;
+      byModel[mk].outputTokens += ev.outputTokens || 0;
+      byModel[mk].totalTokens  += ev.totalTokens  || 0;
+      byModel[mk].costUSD      += ev.costUSD       || 0;
+      byModel[mk].calls        += 1;
+
+      // Por produto
+      const pk = ev.product || "sem produto";
+      if (!byProduct[pk]) byProduct[pk] = { product: pk, totalTokens: 0, costUSD: 0, calls: 0, models: {} };
+      byProduct[pk].totalTokens += ev.totalTokens || 0;
+      byProduct[pk].costUSD     += ev.costUSD      || 0;
+      byProduct[pk].calls       += 1;
+      if (!byProduct[pk].models[ev.model]) byProduct[pk].models[ev.model] = 0;
+      byProduct[pk].models[ev.model] += ev.costUSD || 0;
+
+      // Diário
+      const date = (ev.createdAt || "").slice(0,10);
+      if (date) {
+        if (!dailyMap[date]) dailyMap[date] = { date, totalTokens: 0, costUSD: 0, calls: 0 };
+        dailyMap[date].totalTokens += ev.totalTokens || 0;
+        dailyMap[date].costUSD     += ev.costUSD      || 0;
+        dailyMap[date].calls       += 1;
+      }
+    }
+
+    const models   = Object.values(byModel).sort((a,b) => b.costUSD - a.costUSD);
+    const products = Object.values(byProduct)
+      .map(p => ({ ...p, models: Object.entries(p.models).map(([m,c]) => ({ model:m, costUSD:c })).sort((a,b) => b.costUSD-a.costUSD) }))
+      .sort((a,b) => b.costUSD - a.costUSD);
+    const daily    = Object.values(dailyMap).sort((a,b) => a.date.localeCompare(b.date));
+
+    const totalCostUSD   = models.reduce((s,m) => s + m.costUSD, 0);
+    const totalTokens    = models.reduce((s,m) => s + m.totalTokens, 0);
+    const totalCalls     = models.reduce((s,m) => s + m.calls, 0);
+
+    // Detecta ineficiência: modelo mais caro com mais de 20% do volume
+    const expensive = models[0];
+    const cheap     = models[models.length - 1];
+    let efficiencyAlert = null;
+    if (expensive && cheap && expensive.model !== cheap.model) {
+      const expRate = expensive.totalTokens > 0 ? expensive.costUSD / expensive.totalTokens * 1000 : 0;
+      const chpRate = cheap.totalTokens     > 0 ? cheap.costUSD     / cheap.totalTokens     * 1000 : 0;
+      if (expRate > chpRate * 5 && expensive.costUSD > 0.01) {
+        efficiencyAlert = {
+          expensiveModel: expensive.model,
+          cheapModel:     cheap.model,
+          potentialSaving: parseFloat((expensive.costUSD * 0.7).toFixed(4)),
+        };
+      }
+    }
+
+    return res.json({ ok: true, models, products, daily, totalCostUSD: parseFloat(totalCostUSD.toFixed(4)), totalTokens, totalCalls, efficiencyAlert, source: "sdk" });
+  } catch (err) {
+    console.warn("ai/gateway/usage:", err.message);
+    return res.status(500).json({ error: err.message });
+  }
+});
+
+app.post("/api/chat", requireAuth, async (req, res) => {"""
+
+if OLD in content:
+    content = content.replace(OLD, NEW)
+    with open("server.js", "w") as f:
+        f.write(content)
+    print("✅ Endpoints AI Gateway adicionados ao server.js!")
+else:
+    print("❌ Trecho não encontrado.")
+    sys.exit(1)

package/patch_db.py

@@ -0,0 +1,59 @@
+import sys
+
+with open("db.js", "r") as f:
+    content = f.read()
+
+OLD = """export async function deleteAiService(userId, serviceId) {
+  await client.send(new DeleteItemCommand({
+    TableName: "cb-ai-services",
+    Key: marshall({ userId, serviceId }, { removeUndefinedValues: true }),
+  }));
+}"""
+
+NEW = """export async function deleteAiService(userId, serviceId) {
+  await client.send(new DeleteItemCommand({
+    TableName: "cb-ai-services",
+    Key: marshall({ userId, serviceId }, { removeUndefinedValues: true }),
+  }));
+}
+
+// ─── AI GATEWAY EVENTS ────────────────────────────────────────────────────────
+export async function putAiEvent(event) {
+  await client.send(new PutItemCommand({
+    TableName: "cb-ai-events",
+    Item: marshall(event, { removeUndefinedValues: true }),
+  }));
+}
+
+export async function listAiEvents(userId, days = 30) {
+  const since = new Date();
+  since.setDate(since.getDate() - days);
+  const sinceStr = since.toISOString();
+
+  const res = await client.send(new QueryCommand({
+    TableName:                 "cb-ai-events",
+    KeyConditionExpression:    "userId = :u",
+    FilterExpression:          "createdAt >= :since",
+    ExpressionAttributeValues: marshall({ ":u": userId, ":since": sinceStr }, { removeUndefinedValues: true }),
+  }));
+  return (res.Items || []).map(i => unmarshall(i));
+}
+
+export async function getUserByApiKey(apiKey) {
+  // Scan pelo apiKey — para produção considere GSI no campo apiKey
+  const res = await client.send(new ScanCommand({
+    TableName:        "cb-users",
+    FilterExpression: "apiKey = :k",
+    ExpressionAttributeValues: marshall({ ":k": apiKey }, { removeUndefinedValues: true }),
+  }));
+  return (res.Items || []).map(i => unmarshall(i))[0] || null;
+}"""
+
+if OLD in content:
+    content = content.replace(OLD, NEW)
+    with open("db.js", "w") as f:
+        f.write(content)
+    print("✅ db.js atualizado com putAiEvent, listAiEvents, getUserByApiKey!")
+else:
+    print("❌ Trecho não encontrado.")
+    sys.exit(1)

package/src/client.js

@@ -0,0 +1,154 @@
+/**
+ * CloudBrokerClient — cliente HTTP leve para envio de eventos
+ * Fire-and-forget: nunca bloqueia a aplicação do cliente
+ */
+
+const DEFAULT_AI_ENDPOINT = "https://api.cloudbroker.app.br/api/ai/events";
+const DEFAULT_API_BASE    = "https://api.cloudbroker.app.br/api";
+const RETRY_DELAY_MS      = 30_000; // 30s entre retries
+const MAX_QUEUE_SIZE      = 500;    // máximo de eventos em memória
+
+export class CloudBrokerClient {
+  #apiKey;
+  #aiEndpoint;
+  #apiBase;
+  #queue = [];
+  #flushing = false;
+  #debug;
+
+  constructor({ apiKey, endpoint = DEFAULT_AI_ENDPOINT, apiBase = DEFAULT_API_BASE, debug = false } = {}) {
+    if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
+    this.#apiKey    = apiKey;
+    this.#aiEndpoint = endpoint;
+    this.#apiBase    = apiBase;
+    this.#debug     = debug;
+  }
+
+  /**
+   * Envia um evento de uso de IA
+   * Fire-and-forget — nunca lança erro para o caller
+   */
+  track(event) {
+    try {
+      const payload = {
+        ...event,
+        sdkVersion: "0.1.0",
+        sentAt: new Date().toISOString(),
+      };
+
+      // Adiciona à fila
+      if (this.#queue.length < MAX_QUEUE_SIZE) {
+        this.#queue.push(payload);
+      }
+
+      // Tenta enviar imediatamente em background
+      this.#flush();
+    } catch (err) {
+      if (this.#debug) console.warn("[CloudBroker] track error:", err.message);
+    }
+  }
+
+  /**
+   * Registra um deploy para análise de custo
+   * Fire-and-forget — nunca lança erro para o caller
+   *
+   * @param {object} deploy - Dados do deploy
+   * @param {string} deploy.repo - Repositório (ex: "myapp")
+   * @param {string} deploy.branch - Branch (ex: "main")
+   * @param {string} deploy.prTitle - Título da PR
+   * @param {string} deploy.prUrl - URL da PR
+   * @param {string} deploy.author - Autor do commit
+   * @param {number} deploy.prNumber - Número da PR (GitHub)
+   * @param {string} [deploy.provider="github"] - Provider (github, gitlab, bitbucket)
+   * @param {string} [deploy.terraformPlan] - Saída do `terraform plan`
+   * @param {string} [deploy.dockerfileChanged] - true se Dockerfile foi alterado
+   * @param {number} [deploy.filesChanged] - Número de arquivos alterados
+   * @param {number} [deploy.linesAdded] - Linhas adicionadas
+   * @param {number} [deploy.linesRemoved] - Linhas removidas
+   */
+  trackDeploy(deploy) {
+    if (!deploy) {
+      if (this.#debug) console.warn("[CloudBroker] trackDeploy: deploy é obrigatório");
+      return;
+    }
+
+    // Fire-and-forget: envia para o backend sem bloquear
+    (async () => {
+      try {
+        const payload = {
+          ...deploy,
+          apiKey: this.#apiKey,
+        };
+
+        const res = await fetch(`${this.#apiBase}/analyze/pr`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": this.#apiKey,
+          },
+          body: JSON.stringify(payload),
+          signal: AbortSignal.timeout(5000),
+        });
+
+        if (!res.ok && this.#debug) {
+          console.warn(`[CloudBroker] trackDeploy failed: ${res.status}`);
+        } else if (this.#debug) {
+          console.log("[CloudBroker] deploy registrado com sucesso");
+        }
+      } catch (err) {
+        if (this.#debug) console.warn("[CloudBroker] trackDeploy error:", err.message);
+      }
+    })();
+  }
+
+  async #flush() {
+    if (this.#flushing || this.#queue.length === 0) return;
+    this.#flushing = true;
+
+    const batch = this.#queue.splice(0, 50); // processa até 50 por vez
+
+    try {
+      const res = await fetch(this.#aiEndpoint, {
+        method:  "POST",
+        headers: {
+          "Content-Type":    "application/json",
+          "x-cloudbroker-key": this.#apiKey,
+        },
+        body: JSON.stringify({ events: batch }),
+        signal: AbortSignal.timeout(5000), // timeout de 5s
+      });
+
+      if (!res.ok) {
+        if (this.#debug) console.warn("[CloudBroker] flush failed:", res.status);
+        // Recoloca na fila e agenda retry com backoff — nunca recursa na hora,
+        // senão um erro persistente (ex: 401) martela o endpoint em loop apertado.
+        this.#queue.unshift(...batch);
+        setTimeout(() => { this.#flushing = false; this.#flush(); }, RETRY_DELAY_MS);
+        return;
+      }
+
+      if (this.#debug) console.log(`[CloudBroker] flushed ${batch.length} events`);
+    } catch (err) {
+      // Falha silenciosa — recoloca na fila
+      this.#queue.unshift(...batch);
+      if (this.#debug) console.warn("[CloudBroker] flush error:", err.message);
+
+      // Retry em 30s
+      setTimeout(() => { this.#flushing = false; this.#flush(); }, RETRY_DELAY_MS);
+      return;
+    }
+
+    this.#flushing = false;
+
+    // Se ainda tem eventos na fila, continua
+    if (this.#queue.length > 0) this.#flush();
+  }
+
+  /** Força flush imediato — útil em shutdown */
+  async flushSync() {
+    while (this.#queue.length > 0) {
+      await this.#flush();
+      await new Promise(r => setTimeout(r, 100));
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * cloudbroker-sdk
+ * Token Intelligence & Operational Financial Intelligence
+ *
+ * Uso:
+ *   import { CloudBrokerAI } from "cloudbroker-sdk";
+ *   const openai = CloudBrokerAI.wrap(new OpenAI(), { apiKey: "cb-key-xxx", product: "checkout", team: "mobile" });
+ */
+
+export { CloudBrokerAI } from "./wrapper.js";
+export { CloudBrokerClient } from "./client.js";

package/src/pricing.js

@@ -0,0 +1,32 @@
+/**
+ * Tabela de preços por provider/modelo
+ * Preços em USD por token
+ * Atualizado: Mai/2026
+ */
+export const PRICING = {
+  openai: {
+    "gpt-4o":                   { input: 0.000005,    output: 0.000015   },
+    "gpt-4o-mini":              { input: 0.00000015,  output: 0.0000006  },
+    "gpt-4-turbo":              { input: 0.00001,     output: 0.00003    },
+    "gpt-4":                    { input: 0.00003,     output: 0.00006    },
+    "gpt-3.5-turbo":            { input: 0.0000005,   output: 0.0000015  },
+    "o1":                       { input: 0.000015,    output: 0.00006    },
+    "o1-mini":                  { input: 0.000003,    output: 0.000012   },
+    "text-embedding-3-small":   { input: 0.00000002,  output: 0          },
+    "text-embedding-3-large":   { input: 0.00000013,  output: 0          },
+  },
+  anthropic: {
+    "claude-opus-4-6":          { input: 0.000015,    output: 0.000075   },
+    "claude-sonnet-4-6":        { input: 0.000003,    output: 0.000015   },
+    "claude-sonnet-4-5":        { input: 0.000003,    output: 0.000015   },
+    "claude-haiku-4-5-20251001":{ input: 0.00000025,  output: 0.00000125 },
+    "claude-3-opus-20240229":   { input: 0.000015,    output: 0.000075   },
+    "claude-3-sonnet-20240229": { input: 0.000003,    output: 0.000015   },
+    "claude-3-haiku-20240307":  { input: 0.00000025,  output: 0.00000125 },
+  },
+  gemini: {
+    "gemini-1.5-pro":           { input: 0.0000035,   output: 0.0000105  },
+    "gemini-1.5-flash":         { input: 0.00000035,  output: 0.00000105 },
+    "gemini-2.0-flash":         { input: 0.0000001,   output: 0.0000004  },
+  },
+};

package/src/test.js

@@ -0,0 +1,76 @@
+/**
+ * Teste básico do SDK — simula uma chamada de IA e verifica o tracking
+ * Execute: node src/test.js
+ */
+
+import { CloudBrokerClient } from "./client.js";
+import { CloudBrokerAI } from "./wrapper.js";
+
+console.log("🧪 Testando CloudBroker SDK...\n");
+
+// Testa o cliente
+const client = new CloudBrokerClient({
+  apiKey:   "cb-test-key",
+  endpoint: "http://localhost:3001/api/ai/events",
+  debug:    true,
+});
+
+// Simula um evento
+client.track({
+  provider:      "openai",
+  model:         "gpt-4o",
+  product:       "checkout",
+  team:          "mobile",
+  inputTokens:   1200,
+  outputTokens:  450,
+  totalTokens:   1650,
+  costUSD:       0.00813,
+  latencyMs:     920,
+  endpoint:      "chat.completions",
+});
+
+console.log("✅ Evento trackado (fire-and-forget)\n");
+
+// Simula wrap de cliente OpenAI mock
+const mockOpenAI = {
+  chat: {
+    completions: {
+      create: async (params) => ({
+        model:   params.model,
+        choices: [{ message: { role: "assistant", content: "Resposta simulada" } }],
+        usage:   { prompt_tokens: 100, completion_tokens: 50 },
+      }),
+    },
+  },
+};
+
+const wrapped = CloudBrokerAI.wrap(mockOpenAI, {
+  apiKey:  "cb-test-key",
+  product: "checkout",
+  team:    "mobile",
+  debug:   true,
+});
+
+const res = await wrapped.chat.completions.create({
+  model:    "gpt-4o",
+  messages: [{ role: "user", content: "teste" }],
+});
+
+console.log("✅ Wrap OpenAI funcionando");
+console.log("   Resposta:", res.choices[0].message.content);
+console.log("   Tokens:  ", res.usage);
+
+// Testa trackDeploy
+console.log("\n📦 Testando trackDeploy...");
+wrapped.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,
+});
+console.log("✅ Deploy trackado (fire-and-forget)");

package/src/wrapper.js

@@ -0,0 +1,248 @@
+/**
+ * CloudBrokerAI — wrapper para clientes de IA
+ * Intercepta respostas e registra tokens sem modificar o comportamento original
+ */
+
+import { CloudBrokerClient } from "./client.js";
+import { PRICING } from "./pricing.js";
+
+export class CloudBrokerAI {
+  /**
+   * Envolve um cliente OpenAI ou Anthropic
+   *
+   * @param {object} client     — instância do cliente (new OpenAI() ou Anthropic())
+   * @param {object} options    — configuração
+   * @param {string} options.apiKey    — CloudBroker API key
+   * @param {string} options.product   — nome do produto (ex: "checkout")
+   * @param {string} options.team      — nome do squad (ex: "mobile")
+   * @param {string} options.endpoint  — endpoint CloudBroker (opcional)
+   * @param {boolean} options.debug    — logs de debug (opcional)
+   */
+  static wrap(client, options = {}) {
+    const { apiKey, product, team, endpoint, debug = false } = options;
+    if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
+
+    const cb = new CloudBrokerClient({ apiKey, endpoint, debug });
+
+    // Adiciona trackDeploy ao cliente wrappado
+    client.trackDeploy = cb.trackDeploy.bind(cb);
+
+    // Detecta provider pelo tipo do cliente
+    const isOpenAI    = client?.constructor?.name === "OpenAI"    || !!client?.chat?.completions;
+    const isAnthropic = client?.constructor?.name === "Anthropic" || !!client?.messages?.create;
+
+    if (isOpenAI)    return CloudBrokerAI.#wrapOpenAI(client, cb, { product, team, debug });
+    if (isAnthropic) return CloudBrokerAI.#wrapAnthropic(client, cb, { product, team, debug });
+
+    if (debug) console.warn("[CloudBroker] Provider não reconhecido — retornando cliente original.");
+    return client;
+  }
+
+  /**
+   * Instrumenta um stream (async iterable) sem consumi-lo: substitui o
+   * [Symbol.asyncIterator] para observar cada chunk conforme o consumidor itera,
+   * preservando o objeto original (.tee(), .controller, etc.). Ao terminar a
+   * iteração (ou em erro), dispara onDone com o usage acumulado.
+   *
+   * @param {AsyncIterable} stream  — stream retornado pelo provider
+   * @param {(chunk:any)=>void} onChunk — acumula usage a partir de cada chunk
+   * @param {()=>void} onDone — chamado ao fim da iteração (fire-and-forget)
+   */
+  static #instrumentStream(stream, onChunk, onDone) {
+    if (!stream || typeof stream[Symbol.asyncIterator] !== "function") return stream;
+    // Captura o método original e dirige o iterador via .next() — nunca via
+    // for-await sobre o resultado, senão um generator (cujo asyncIterator retorna
+    // ele mesmo) reentraria no método já substituído e causaria recursão infinita.
+    const originalMethod = stream[Symbol.asyncIterator].bind(stream);
+    stream[Symbol.asyncIterator] = function () {
+      const source = originalMethod();
+      return (async function* () {
+        try {
+          while (true) {
+            const { value, done } = await source.next();
+            if (done) return;
+            try { onChunk(value); } catch { /* não interfere no consumo */ }
+            yield value;
+          }
+        } finally {
+          try { onDone(); } catch { /* fire-and-forget */ }
+        }
+      })();
+    };
+    return stream;
+  }
+
+  static #wrapOpenAI(client, cb, { product, team, debug }) {
+    const originalCreate = client.chat.completions.create.bind(client.chat.completions);
+
+    client.chat.completions.create = async (params, options) => {
+      const start = Date.now();
+
+      // ── Streaming: pede usage no chunk final e instrumenta o iterador ────────
+      if (params?.stream) {
+        const streamParams = {
+          ...params,
+          stream_options: { include_usage: true, ...(params.stream_options || {}) },
+        };
+        const stream = await originalCreate(streamParams, options);
+
+        let model = params.model || "unknown";
+        let inputTokens = 0, outputTokens = 0;
+        const onChunk = (chunk) => {
+          if (chunk?.model) model = chunk.model;
+          if (chunk?.usage) {
+            inputTokens  = chunk.usage.prompt_tokens     || inputTokens;
+            outputTokens = chunk.usage.completion_tokens || outputTokens;
+          }
+        };
+        const onDone = () => {
+          try {
+            const pricing = PRICING.openai[model] || PRICING.openai["gpt-4o"];
+            const costUSD = (inputTokens * pricing.input) + (outputTokens * pricing.output);
+            cb.track({
+              provider:    "openai",
+              model,
+              product:     product || null,
+              team:        team    || null,
+              inputTokens,
+              outputTokens,
+              totalTokens: inputTokens + outputTokens,
+              costUSD:     parseFloat(costUSD.toFixed(6)),
+              latencyMs:   Date.now() - start,
+              endpoint:    "chat.completions",
+              streaming:   true,
+            });
+          } catch (err) {
+            if (debug) console.warn("[CloudBroker] track error:", err.message);
+          }
+        };
+
+        return CloudBrokerAI.#instrumentStream(stream, onChunk, onDone);
+      }
+
+      // ── Não-streaming ───────────────────────────────────────────────────────
+      const res = await originalCreate(params, options);
+      const ms  = Date.now() - start;
+
+      // Fire-and-forget
+      try {
+        const model        = res.model || params.model || "unknown";
+        const inputTokens  = res.usage?.prompt_tokens     || 0;
+        const outputTokens = res.usage?.completion_tokens || 0;
+        const pricing      = PRICING.openai[model] || PRICING.openai["gpt-4o"];
+        const costUSD      = (inputTokens * pricing.input) + (outputTokens * pricing.output);
+
+        cb.track({
+          provider:      "openai",
+          model,
+          product:       product || null,
+          team:          team    || null,
+          inputTokens,
+          outputTokens,
+          totalTokens:   inputTokens + outputTokens,
+          costUSD:       parseFloat(costUSD.toFixed(6)),
+          latencyMs:     ms,
+          endpoint:      "chat.completions",
+        });
+      } catch (err) {
+        if (debug) console.warn("[CloudBroker] track error:", err.message);
+      }
+
+      return res;
+    };
+
+    return client;
+  }
+
+  static #wrapAnthropic(client, cb, { product, team, debug }) {
+    const originalCreate = client.messages.create.bind(client.messages);
+
+    client.messages.create = async (params, options) => {
+      const start = Date.now();
+
+      // ── Streaming: acumula usage dos eventos message_start / message_delta ───
+      if (params?.stream) {
+        const stream = await originalCreate(params, options);
+
+        let model = params.model || "unknown";
+        let inputTokens = 0, outputTokens = 0;
+        const onChunk = (event) => {
+          if (event?.type === "message_start" && event.message) {
+            model        = event.message.model || model;
+            inputTokens  = event.message.usage?.input_tokens  || inputTokens;
+            outputTokens = event.message.usage?.output_tokens || outputTokens;
+          } else if (event?.type === "message_delta" && event.usage) {
+            // message_delta traz o total acumulado de output_tokens
+            outputTokens = event.usage.output_tokens || outputTokens;
+          }
+        };
+        const onDone = () => {
+          try {
+            const pricing = PRICING.anthropic[model] || PRICING.anthropic["claude-sonnet-4-6"];
+            const costUSD = (inputTokens * pricing.input) + (outputTokens * pricing.output);
+            cb.track({
+              provider:    "anthropic",
+              model,
+              product:     product || null,
+              team:        team    || null,
+              inputTokens,
+              outputTokens,
+              totalTokens: inputTokens + outputTokens,
+              costUSD:     parseFloat(costUSD.toFixed(6)),
+              latencyMs:   Date.now() - start,
+              endpoint:    "messages",
+              streaming:   true,
+            });
+          } catch (err) {
+            if (debug) console.warn("[CloudBroker] track error:", err.message);
+          }
+        };
+
+        return CloudBrokerAI.#instrumentStream(stream, onChunk, onDone);
+      }
+
+      // ── Não-streaming ───────────────────────────────────────────────────────
+      const res = await originalCreate(params, options);
+      const ms  = Date.now() - start;
+
+      try {
+        const model        = res.model || params.model || "unknown";
+        const inputTokens  = res.usage?.input_tokens  || 0;
+        const outputTokens = res.usage?.output_tokens || 0;
+        const pricing      = PRICING.anthropic[model] || PRICING.anthropic["claude-sonnet-4-6"];
+        const costUSD      = (inputTokens * pricing.input) + (outputTokens * pricing.output);
+
+        cb.track({
+          provider:      "anthropic",
+          model,
+          product:       product || null,
+          team:          team    || null,
+          inputTokens,
+          outputTokens,
+          totalTokens:   inputTokens + outputTokens,
+          costUSD:       parseFloat(costUSD.toFixed(6)),
+          latencyMs:     ms,
+          endpoint:      "messages",
+        });
+      } catch (err) {
+        if (debug) console.warn("[CloudBroker] track error:", err.message);
+      }
+
+      return res;
+    };
+
+    return client;
+  }
+
+  /**
+   * Registra um deploy para análise de custo
+   * Atalho para CloudBrokerClient.trackDeploy() sem precisar envolver um cliente de IA
+   *
+   * @param {string} apiKey - CloudBroker API key
+   * @param {object} deploy - Dados do deploy (repo, branch, prTitle, etc)
+   */
+  static trackDeploy(apiKey, deploy) {
+    const cb = new CloudBrokerClient({ apiKey });
+    cb.trackDeploy(deploy);
+  }
+}