cloudbroker-sdk 0.5.0 → 0.7.0

package/.github/workflows/publish.yml

@@ -4,7 +4,16 @@ on:
   push:
     branches: [main]
     paths:
+      # Sem barra inicial: filtros de path do GitHub Actions são relativos à
+      # raiz do repo e '/package.json' não casa com nada — o workflow deixou de
+      # disparar por completo (o 0.6.0 foi mergeado e nunca publicado).
+      # 'package.json' já cobre só a raiz: sem '**', o glob não atravessa
+      # diretórios, que era a intenção original de ancorar.
       - 'package.json'
+  # Escape hatch: quando o filtro acima não dispara (foi o caso do 0.6.0, que
+  # entrou no main sem publicar), dá pra publicar a versão que está no main sem
+  # precisar de um bump artificial só pra acionar o gatilho.
+  workflow_dispatch:
 
 jobs:
   publish:
@@ -22,6 +31,15 @@ jobs:
           node-version: 20
           registry-url: 'https://registry.npmjs.org'
 
+      # Gate de teste antes do publish — este pacote roda DENTRO da aplicação
+      # de produção do cliente; publicar sem rodar a suíte já era um risco
+      # aberto (nenhum CI de teste existia neste repo).
+      - name: Instalar dependências de teste
+        run: npm ci || npm install
+
+      - name: Rodar testes
+        run: npm test
+
       - name: Publish to npm
         run: npm publish
         env:

package/README.md

@@ -46,6 +46,62 @@ const res = await anthropic.messages.create({
 });
 ```
 
+## Uso com Gemini
+
+```js
+import { GoogleGenAI } from "@google/genai";
+import { CloudBrokerAI } from "cloudbroker-sdk";
+
+const gemini = CloudBrokerAI.wrap(new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }), {
+  apiKey:  "cb-key-xxxx",
+  product: "checkout",
+  team:    "mobile",
+});
+
+const res = await gemini.models.generateContent({
+  model:    "gemini-2.5-flash",
+  contents: "Olá!",
+});
+```
+
+O `cbLabel` pode ir no próprio params (a API do Gemini é de argumento único) ou
+no segundo argumento, como nos outros wrappers. Nos dois casos ele é removido
+antes de a chamada seguir pro Google:
+
+```js
+await gemini.models.generateContent({
+  model: "gemini-2.5-flash", contents: "…", cbLabel: "checkout:resumo-pedido",
+});
+```
+
+### Por que o custo do Gemini não é `input × preço + output × preço`
+
+A conta do Gemini tem três particularidades. Ignorar qualquer uma delas erra o
+valor de forma relevante, então o SDK trata as três:
+
+| Particularidade | O que acontece se ignorar |
+|---|---|
+| `promptTokenCount` **já inclui** os tokens servidos de cache, que custam ~10x menos | superfatura a parcela cacheada (1,65x a mais num prompt 80% cacheado) |
+| `thoughtsTokenCount` é separado de `candidatesTokenCount` e é cobrado como output | subfatura — 33x a menos num caso com 2000 thinking tokens |
+| 2.5 Pro dobra de preço acima de 200k tokens de prompt; áudio na entrada custa mais que texto | subfatura prompts longos e entrada de áudio |
+
+### Limitações declaradas
+
+- **O custo é estimado por tabela de preço local**, não lido de uma fatura. O
+  Gemini não expõe API de uso ou custo por chave — só o dashboard do AI Studio
+  e o console do Cloud Billing. Os preços são os do paid tier publicados em
+  `ai.google.dev/gemini-api/docs/pricing`, conferidos em 2026-08-02, e **não
+  foram calibrados contra fatura real**.
+- **Free tier sai com custo > 0.** A tabela é a do paid tier; quem está no free
+  tier vê o valor que *pagaria*, não o que paga.
+- **Modelo fora da tabela não recebe preço de outro modelo.** O evento vai com
+  `costUSD: null` e `unpriced: true`, preservando os tokens. Variante com sufixo
+  (`-preview-…`) é precificada pelo modelo base e marcada `approxPricing`.
+- **Armazenamento de contexto em cache não é cobrado aqui.** O Google cobra por
+  hora de cache ativo (US$ 1,00/h na maioria dos modelos); isso não aparece no
+  `usageMetadata` de uma chamada e não é modelado.
+- **Batch API não é modelada** — o Google cobra metade nesse modo.
+
 ## Streaming
 
 Chamadas com `stream: true` também são rastreadas — o SDK observa os chunks
@@ -106,14 +162,17 @@ CloudBrokerAI.trackDeploy("cb-key-xxxx", {
 });
 ```
 
-## Custo de nuvem a nível de código (MVP)
+## Cost per Feature — Rastreie Custo por Feature
 
-Atribua custo de **AWS** a um trecho de código / produto. O SDK envolve um client
-do AWS SDK v3 e, a cada `.send()`, estima o custo (requests + transferência) e
+Atribua custo de **AWS** e **Azure** a cada feature/módulo sua. O SDK envolve um
+client do provedor e, a cada chamada, estima o custo (requests + transferência) e
 registra um evento — mesmo padrão fire-and-forget do wrapper de IA.
 
-> MVP: AWS apenas, serviços **S3** e **DynamoDB**, região `us-east-2`. Armazenamento
-> GB-mês, Azure e atribuição automática (stack-trace) estão fora do MVP.
+**👉 [Guia Completo](./docs/COST_PER_FEATURE.md)** — Setup (5 min), exemplos, FAQ.
+
+> Escopo atual — AWS: **S3** e **DynamoDB** (`us-east-2`); Azure: **Blob Storage**
+> e **Cosmos DB** (`eastus2`). Armazenamento GB-mês e atribuição automática
+> (stack-trace) estão fora do MVP.
 
 ```js
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
@@ -146,6 +205,81 @@ Cada chamada gera um evento `POST /api/cloud/events` com `service`, `operation`,
 `product`, `team`, `label`, `requests`, `bytesIn`/`bytesOut`, `costUSD` estimado e
 `latencyMs`. O `cbLabel` nunca é repassado ao AWS SDK.
 
+### Azure — Blob Storage e Cosmos DB
+
+O Azure SDK não tem um `.send()` único como o AWS SDK v3: cada sub-client tem
+métodos próprios. Por isso o `wrapAzure` intercepta a **cadeia de sub-clients** —
+as fábricas (`getContainerClient`, `database`/`container`) devolvem sub-clients já
+embrulhados, e só os métodos de data-plane conhecidos são rastreados. Qualquer
+método fora dessa lista passa intocado.
+
+```js
+import { BlobServiceClient } from "@azure/storage-blob";
+import { CloudBrokerCloud } from "cloudbroker-sdk";
+
+const blobSvc = CloudBrokerCloud.wrapAzure(
+  BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION),
+  { apiKey: "cb-key-xxxx", product: "checkout", team: "mobile" },
+);
+
+// label opcional dentro do objeto de options nativo do método
+await blobSvc
+  .getContainerClient("docs")
+  .getBlockBlobClient("nf.pdf")
+  .uploadData(buf, { cbLabel: "upload-nota-fiscal" });
+```
+
+Cosmos DB usa o **`requestCharge` (RUs) real** que o servidor devolve em cada
+resposta — custo por unidade cobrada de verdade, não aproximação por request:
+
+```js
+import { CosmosClient } from "@azure/cosmos";
+
+const cosmos = CloudBrokerCloud.wrapAzure(new CosmosClient(conn), {
+  apiKey: "cb-key-xxxx", product: "checkout",
+});
+const orders = cosmos.database("loja").container("pedidos");
+
+await orders.items.create({ id: "123" }, { cbLabel: "criar-pedido" });
+await orders.items.query("SELECT * FROM c").fetchAll(); // RUs do query também contam
+```
+
+O `expressMiddleware` (abaixo) funciona igual pros dois provedores — mesma
+prioridade de `label`/`product`/`team`, sem precisar de `cbLabel` manual.
+
+> **Precisão e premissas — leia antes de tratar o número como fechado:**
+>
+> - **Cosmos:** as RUs são as **reais** devolvidas pelo servidor em cada resposta
+>   (`requestCharge`). O **preço por RU** assume o modelo **serverless**. Em
+>   *throughput provisionado* (manual ou autoscale) a Azure cobra RU/s reservada
+>   por hora, independentemente do consumo — esse modelo ainda não é representado,
+>   então o custo calculado não corresponde à fatura nesse caso.
+> - **Blob:** estimado por classe de operação (write/read/list), assumindo tier
+>   **Hot** e redundância **LRS**. Cool/Archive e GRS/ZRS têm outro preço.
+> - **Transferência de saída:** cobrada sobre todo `bytesOut`. A Azure não cobra
+>   saída intra-região e concede franquia mensal — para um app rodando na mesma
+>   região do Storage, este termo **superestima**.
+> - **Região:** só `eastus2` tem tabela de preço. Em outra região o evento é
+>   registrado com `costUSD: null` e `billingUnit: "*-region-unpriced"` — a
+>   operação aparece no relatório, mas sem custo inventado.
+> - **Reconciliação:** a tela compara o estimado contra o custo real do Cost
+>   Management e mostra o **desvio**; o ajuste da tabela é manual (não há
+>   recalibração automática).
+> - **Listagem:** `listBlobsFlat`/`listContainers` devolvem iterator preguiçoso —
+>   o evento só é emitido quando uma página é de fato buscada. Percorrendo com
+>   `for await`, contamos **1 operação** mesmo que o SDK pagine internamente;
+>   use `.byPage()` para contagem por página.
+> - **Cosmos `for await` direto** (`getAsyncIterator`) não é instrumentado —
+>   use `fetchAll()`/`fetchNext()`.
+> - **Delete** no tier Hot é grátis: sai com custo `0` e
+>   `billingUnit: "blob-free"`, sem sumir do relatório.
+>
+> ⚠️ **Ainda não calibrado contra uma fatura Azure real.** A estrutura é
+> exercitada contra os SDKs oficiais (`@azure/storage-blob`, `@azure/cosmos`) na
+> suíte de testes, mas os valores da tabela de preço Azure não foram conferidos
+> contra a página oficial nem contra uma fatura. Trate o custo Azure como ordem
+> de grandeza até rodar a reconciliação na sua conta.
+
 ### Atribuição automática por requisição (Express)
 
 Em vez de passar `cbLabel` em cada `.send()`, use o middleware: todas as chamadas

package/docs/COST_PER_FEATURE.md

@@ -0,0 +1,296 @@
+# CloudBroker SDK — Rastreie Custo por Feature
+
+## O Que É?
+
+Instrumentar sua aplicação com o CloudBroker SDK permite rastrear **quanto cada feature/módulo seu custa em AWS e Azure**.
+
+```javascript
+// Seu código
+await s3.putObject({ ... }, { cbLabel: 'invoice-generation' });
+// CloudBroker registra: feature 'invoice-generation' custou $0.00042
+```
+
+**Result:** Dashboard mostra "invoice-generation: $X/mês".
+
+---
+
+## Setup Rápido (5 minutos)
+
+### 1. Instalar
+
+```bash
+npm install cloudbroker-sdk
+```
+
+### 2. Gerar API Key
+
+1. Acesse https://app.cloudbroker.app.br
+2. Configurações → API Keys
+3. Criar nova key do tipo **SDK** (só Admin pode criar keys SDK)
+4. Copiar: `cb_live_...` — **o valor é exibido uma única vez**; depois só o
+   prefixo mascarado fica visível. Se perder, gere outra.
+
+### 3. Instrumentar Backend
+
+```javascript
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
+import { CloudBrokerCloud } from "cloudbroker-sdk";
+
+// S3
+const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: "us-east-2" }), {
+  apiKey: process.env.CLOUDBROKER_API_KEY,
+  product: "checkout-service",  // seu app
+  team: "payments",             // seu squad
+});
+
+// DynamoDB
+const dynamodb = CloudBrokerCloud.wrapAWS(
+  DynamoDBDocumentClient.from(new DynamoDBClient({ region: "us-east-2" })),
+  { apiKey: process.env.CLOUDBROKER_API_KEY, product: "checkout-service", team: "payments" }
+);
+```
+
+### 4. Adicionar Labels
+
+```javascript
+// S3 upload com label
+await s3.send(new PutObjectCommand({
+  Bucket: 'invoices',
+  Key: `${orderId}.pdf`,
+  Body: pdfBuffer,
+}), {
+  cbLabel: 'invoice-generation',  // ← Identifica a feature
+});
+
+// DynamoDB insert com label
+await dynamodb.send(new PutCommand({
+  TableName: 'Orders',
+  Item: { orderId, status: 'pending' },
+}), {
+  cbLabel: 'order-processing',  // ← Identifica a feature
+});
+```
+
+### 5. Ver Custos
+
+Dashboard: **CloudBroker App → Custo por Código**
+
+```
+Feature: order-processing
+  Requests: 3,456
+  Total: $87.50
+  Per Request: $0.0253 ✅
+
+Feature: invoice-generation
+  Requests: 1,234
+  Total: $10.20
+  Per Request: $0.00828 ✅
+```
+
+---
+
+## Azure — Blob Storage e Cosmos DB
+
+O SDK da Azure não tem um `.send()` único como o AWS SDK v3, então o `wrapAzure`
+intercepta a **cadeia de sub-clients**: as fábricas (`getContainerClient`,
+`database`/`container`) devolvem sub-clients já instrumentados.
+
+```javascript
+import { BlobServiceClient } from "@azure/storage-blob";
+import { CloudBrokerCloud } from "cloudbroker-sdk";
+
+const blobSvc = CloudBrokerCloud.wrapAzure(
+  BlobServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION),
+  { apiKey: "cb_live_...", product: "checkout", team: "mobile" },
+);
+
+await blobSvc
+  .getContainerClient("docs")
+  .getBlockBlobClient("nf.pdf")
+  .uploadData(buf, { cbLabel: "upload-nota-fiscal" });
+```
+
+Cosmos DB usa o `requestCharge` (RUs) **real** devolvido pelo servidor:
+
+```javascript
+import { CosmosClient } from "@azure/cosmos";
+
+const cosmos = CloudBrokerCloud.wrapAzure(new CosmosClient(conn), {
+  apiKey: "cb_live_...", product: "checkout",
+});
+const pedidos = cosmos.database("loja").container("pedidos");
+
+await pedidos.items.create({ id: "123" }, { cbLabel: "criar-pedido" });
+await pedidos.items.query("SELECT * FROM c").fetchAll();
+```
+
+O `expressMiddleware` funciona igual para AWS e Azure.
+
+**Premissas que mudam o número** (detalhe completo no
+[README](../README.md#cost-per-feature--rastreie-custo-por-feature)):
+
+| Item | Situação |
+|---|---|
+| Cosmos — RUs | Reais (`requestCharge` do servidor) |
+| Cosmos — preço por RU | Assume **serverless**. Throughput provisionado não é modelado |
+| Blob | Estimado por classe de operação; assume tier **Hot** + **LRS** |
+| Egress | Cobrado sobre todo `bytesOut` (a Azure não cobra intra-região) |
+| Região | Só `eastus2` tem preço; outras saem com `costUSD: null` |
+| `for await` no Cosmos | Não instrumentado — use `fetchAll()`/`fetchNext()` |
+| Calibração | ⚠️ **Não conferido contra fatura Azure real ainda** |
+
+---
+
+## Convenção de Labels
+
+Use nomes **descritivos** que refletem features/módulos:
+
+| Feature | Label | Exemplos de Operações |
+|---------|-------|----------------------|
+| Checkout | `order-processing` | Criar pedido, persistir dados |
+| Geração de Invoice | `invoice-generation` | Upload de PDF, armazenamento |
+| Detecção de Fraude | `fraud-detection` | Análise de padrões, lookup histórico |
+| Analytics | `analytics-tracking` | Coleta de eventos, agregação |
+| Admin Panel | `admin-reports` | Geração de relatórios, queries |
+
+**Regras:**
+- ✅ Use labels **finitos** (não criar um label por request)
+- ✅ Labels **descritivos** (não `x1`, `x2`, etc)
+- ✅ Use **kebab-case** (`order-processing`, não `orderProcessing`)
+
+❌ **EVITAR:**
+```javascript
+// Ruim: label infinito (1 por request)
+cbLabel: `order-${order.id}`
+
+// Ruim: não descritivo
+cbLabel: 'x1'
+
+// Bom: finito e descritivo
+cbLabel: 'order-processing'
+```
+
+---
+
+## Exemplo Completo
+
+```javascript
+import express from 'express';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';
+import { CloudBrokerCloud } from 'cloudbroker-sdk';
+
+const app = express();
+
+// Setup
+const s3 = CloudBrokerCloud.wrapAWS(new S3Client(), {
+  apiKey: process.env.CLOUDBROKER_API_KEY,
+  product: 'checkout-service',
+  team: 'payments',
+});
+
+const dynamodb = CloudBrokerCloud.wrapAWS(
+  DynamoDBDocumentClient.from(new DynamoDBClient()),
+  { apiKey: process.env.CLOUDBROKER_API_KEY, product: 'checkout-service', team: 'payments' }
+);
+
+// POST /orders — cria pedido com 2 features diferentes
+app.post('/orders', async (req, res) => {
+  const order = { orderId: `order-${Date.now()}`, ...req.body };
+
+  // Feature 1: Persistir pedido
+  await dynamodb.send(new PutCommand({
+    TableName: 'Orders',
+    Item: order,
+  }), {
+    cbLabel: 'order-processing',
+  });
+
+  // Feature 2: Gerar invoice
+  await s3.send(new PutObjectCommand({
+    Bucket: 'invoices',
+    Key: `${order.orderId}.json`,
+    Body: JSON.stringify(order),
+  }), {
+    cbLabel: 'invoice-generation',
+  });
+
+  res.json({ ok: true, orderId: order.orderId });
+});
+
+app.listen(3000);
+```
+
+**Result no Dashboard:**
+- `order-processing`: $X/mês
+- `invoice-generation`: $Y/mês
+
+---
+
+## FAQ
+
+**P: Quanto tempo leva pra aparecer no dashboard?**
+A: ~5 minutos (batch em DynamoDB).
+
+**P: E se não colocar label?**
+A: Ainda rastreia como `null` (agrupa sem label).
+
+**P: Posso mudar o label depois?**
+A: Não — é histórico. Use um novo label a partir de agora.
+
+**P: Qual é o overhead?**
+A: <1% CPU (fire-and-forget, não bloqueia requests).
+
+**P: Funciona em todas as regiões?**
+A: Hoje há tabela de preço para `us-east-2` (AWS) e `eastus2` (Azure). Em outra
+região a operação é registrada com `costUSD: null` e `billingUnit`
+`*-region-unpriced` — aparece no relatório, mas sem custo estimado (preferimos
+não exibir o preço de outra região como se fosse o seu).
+
+**P: E se der erro no rastreamento?**
+A: Silencioso — seu request continua normal (fail-soft).
+
+---
+
+## Troubleshooting
+
+### Nenhum dado aparecendo no dashboard?
+
+1. ✅ API Key configurada?
+   ```bash
+   echo $CLOUDBROKER_API_KEY
+   ```
+
+2. ✅ CloudBrokerCloud.wrapAWS() chamado?
+   ```javascript
+   const s3 = CloudBrokerCloud.wrapAWS(new S3Client(), { apiKey, product, team });
+   ```
+
+3. ✅ cbLabel adicionado?
+   ```javascript
+   await s3.send(cmd, { cbLabel: 'seu-label' });
+   ```
+
+4. ✅ Esperou 5+ minutos?
+   (CloudBroker faz batch, não é real-time)
+
+### Custo aparecendo como $0?
+
+- Normal no MVP (estimativa simplificada, reconciliação depois)
+- Operações muito baratas podem ficar abaixo do centavo
+
+---
+
+## Próximos Passos
+
+- **Exemplo funcional:** Veja `example-checkout-app` no repo
+- **Mais Serviços:** Lambda, SQS, SNS; Azure Functions, Service Bus (roadmap)
+- **OpenTelemetry:** Rastrear custom operations (futuro)
+
+---
+
+## Suporte
+
+Dúvidas? Abra issue no [GitHub](https://github.com/cloudbroker-app/cloudbroker-sdk).

package/example-checkout-app/.env.example

@@ -0,0 +1,13 @@
+# AWS Configuration
+AWS_REGION=us-east-2
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+
+# CloudBroker Configuration
+CLOUDBROKER_API_KEY=sk_1234...
+CLOUDBROKER_PRODUCT=checkout-example
+CLOUDBROKER_TEAM=platform
+
+# App Configuration
+PORT=3000
+NODE_ENV=development