cloudbroker-sdk 0.5.0 → 0.6.0

package/src/pricing-cloud.js

@@ -1,8 +1,23 @@
 /**
  * Tabela de preços de nuvem (curada, MVP) — atribuição de custo a nível de código.
- * Escopo MVP: AWS, região us-east-2, serviços S3 e DynamoDB.
+ * Escopo: AWS (us-east-2: S3, DynamoDB) e Azure (eastus2: Blob Storage, Cosmos DB).
  * Componentes: requests + transferência de dados (armazenamento GB-mês fora do MVP).
- * Preços em USD. Atualizado: Jun/2026.
+ * Preços em USD.
+ *
+ * PROVENIÊNCIA (importante — não trocar por uma data sem conferir de novo):
+ * - AWS (us-east-2, S3/DynamoDB): conferido contra a tabela oficial em Jun/2026.
+ * - Azure (eastus2, Blob Hot/LRS + Cosmos serverless): valores de referência
+ *   NÃO conferidos contra a página oficial de preços. São plausíveis, não
+ *   verificados — a reconciliação contra o Cost Management é o que mede o
+ *   desvio real. Conferir antes de tratar o custo Azure como número fechado.
+ *
+ * Premissas que mudam o resultado (ver README):
+ * - Blob: tier Hot, redundância LRS. Cool/Archive e GRS/ZRS têm outro preço.
+ * - Cosmos: modelo serverless. Em throughput provisionado a cobrança é por
+ *   RU/s reservada por hora — modelo que este SDK não representa.
+ * - Egress: cobrado sobre todo bytesOut. A Azure não cobra saída intra-região
+ *   e dá franquia mensal — em app rodando dentro da mesma região, este termo
+ *   superestima.
  */
 export const CLOUD_PRICING = {
   aws: {
@@ -21,6 +36,24 @@ export const CLOUD_PRICING = {
       },
     },
   },
+  azure: {
+    eastus2: {
+      blob: {
+        // Hot tier, LRS — por operação (preço por unidade — já dividido por 10.000).
+        // List/Create Container é cobrado na mesma faixa de write pela Azure.
+        write: 0.055 / 10_000,
+        read:  0.0044 / 10_000,
+        list:  0.055 / 10_000,
+        // transferência de saída para a internet — 1ª faixa (simplificado), por GB
+        transferOutPerGB: 0.087,
+      },
+      cosmosdb: {
+        // serverless — por 1M Request Units. O custo real vem do requestCharge
+        // (RUs) que o próprio Cosmos retorna em cada resposta.
+        perMillionRU: 0.25,
+      },
+    },
+  },
 };
 
 const GB = 1024 * 1024 * 1024;
@@ -39,21 +72,99 @@ const DDB_READ_OPS = new Set([
   "GetItem", "Query", "Scan", "BatchGetItem", "TransactGetItems",
 ]);
 
+/**
+ * Blob Storage — FONTE ÚNICA de "o que é interceptado" e "como é cobrado".
+ * O wrapper (cloud-wrapper.js) itera esta mesma tabela pra saber quais métodos
+ * embrulhar, então é impossível um método ser precificado sem ser rastreado
+ * (ou o contrário).
+ *
+ * - `kind`      — classe de cobrança da Azure (write/read/list/free)
+ * - `optIdx`    — índice a partir do qual o options bag pode aparecer. Protege
+ *                 argumentos de DADO do cliente de serem inspecionados/alterados.
+ * - `bodyIdx`   — índice do argumento de corpo (pra medir bytesIn). null = não medido.
+ * - `transfers` — a operação de fato trafega o conteúdo (conta egress).
+ *                 `getProperties`/`exists` devolvem contentLength mas NÃO
+ *                 transferem o blob — contá-lo cobrava egress de um GET de
+ *                 metadado (erro de ordens de grandeza).
+ */
+export const AZURE_BLOB_OPS = {
+  upload:            { kind: "write", optIdx: 2, bodyIdx: 0 },
+  uploadData:        { kind: "write", optIdx: 1, bodyIdx: 0 },
+  uploadFile:        { kind: "write", optIdx: 1, bodyIdx: null },
+  uploadStream:      { kind: "write", optIdx: 3, bodyIdx: null },
+  uploadBlockBlob:   { kind: "write", optIdx: 3, bodyIdx: 1 },
+  appendBlock:       { kind: "write", optIdx: 2, bodyIdx: 0 },
+  uploadPages:       { kind: "write", optIdx: 3, bodyIdx: 0 },
+  stageBlock:        { kind: "write", optIdx: 3, bodyIdx: 1 },
+  commitBlockList:   { kind: "write", optIdx: 1, bodyIdx: null },
+  syncCopyFromURL:   { kind: "write", optIdx: 1, bodyIdx: null },
+  create:            { kind: "write", optIdx: 0, bodyIdx: null },
+  createIfNotExists: { kind: "write", optIdx: 0, bodyIdx: null },
+  setMetadata:       { kind: "write", optIdx: 1, bodyIdx: null },
+  setHTTPHeaders:    { kind: "write", optIdx: 1, bodyIdx: null },
+
+  download:          { kind: "read",  optIdx: 0, bodyIdx: null, transfers: true },
+  downloadToBuffer:  { kind: "read",  optIdx: 0, bodyIdx: null, transfers: true },
+  downloadToFile:    { kind: "read",  optIdx: 1, bodyIdx: null, transfers: true },
+  exists:            { kind: "read",  optIdx: 0, bodyIdx: null },
+  getProperties:     { kind: "read",  optIdx: 0, bodyIdx: null },
+
+  // Grátis no tier Hot — evento é emitido mesmo assim (custo 0), pra operação
+  // não sumir do relatório.
+  delete:            { kind: "free",  optIdx: 0, bodyIdx: null },
+  deleteIfExists:    { kind: "free",  optIdx: 0, bodyIdx: null },
+  deleteBlob:        { kind: "free",  optIdx: 1, bodyIdx: null },
+};
+
+/** list* devolvem iterator LAZY — cobrados como write pela Azure. */
+export const AZURE_BLOB_ITERATOR_OPS = ["listBlobsFlat", "listBlobsByHierarchy", "listContainers"];
+
+/** read/replace/delete/patch existem em Item, Container E Database. */
+export const AZURE_COSMOS_NODE_OPS = {
+  read:    { optIdx: 0 },
+  replace: { optIdx: 1 },
+  delete:  { optIdx: 0 },
+  patch:   { optIdx: 1 },
+};
+export const AZURE_COSMOS_ITEMS_OPS = {
+  create: { optIdx: 1 },
+  upsert: { optIdx: 1 },
+  batch:  { optIdx: 1 },
+  bulk:   { optIdx: 1 },
+};
+export const AZURE_COSMOS_ITEMS_ITERATOR_OPS = {
+  query:   { optIdx: 1 },
+  readAll: { optIdx: 0 },
+};
+
+// Fallback de RU quando a resposta não traz requestCharge (raro em resposta
+// real). Sai marcado como `cosmos-ru-est`, distinto de `cosmos-ru` medido.
+const COSMOS_WRITE_SUFFIX = /\.(create|upsert|replace|delete|patch|batch|bulk)(\.|$)/;
+const COSMOS_FALLBACK_RU = { write: 5, read: 1 };
+
 /**
  * Classifica a operação e estima o custo USD de uma única chamada.
- * MVP: aproxima 1 unidade de capacidade por request (não conhece o tamanho do item
- * com precisão); a reconciliação contra o Cost Explorer corrige o desvio agregado.
+ * AWS: aproxima 1 unidade de capacidade por request (não conhece o tamanho do
+ * item com precisão). Azure Cosmos: usa o requestCharge (RUs) REAL retornado
+ * pelo servidor quando disponível. A reconciliação contra Cost Explorer/Cost
+ * Management corrige o desvio agregado.
  *
  * @param {object} p
- * @param {string} p.service    — "s3" | "dynamodb"
- * @param {string} p.operation  — nome da operação sem o sufixo "Command" (ex: "PutObject")
+ * @param {string} [p.provider="aws"] — "aws" | "azure"
+ * @param {string} p.service    — "s3" | "dynamodb" | "blob" | "cosmosdb"
+ * @param {string} p.operation  — AWS: nome da operação sem "Command" (ex: "PutObject");
+ *                                Azure: nome do método interceptado (ex: "upload", "items.create")
  * @param {number} [p.requests=1]
- * @param {number} [p.bytesOut=0] — bytes transferidos de saída (ex: ContentLength de um GetObject)
- * @param {string} [p.region="us-east-2"]
+ * @param {number} [p.bytesOut=0] — bytes transferidos de saída
+ * @param {number} [p.requestCharge] — RUs reais da resposta do Cosmos (Azure)
+ * @param {string} [p.region] — default us-east-2 (AWS) / eastus2 (Azure)
  * @returns {{ costUSD:number, billingUnit:string }}
  */
-export function estimateCloudCost({ service, operation, requests = 1, bytesOut = 0, region = "us-east-2" }) {
-  const regionTable = CLOUD_PRICING.aws[region] || CLOUD_PRICING.aws["us-east-2"];
+export function estimateCloudCost({ provider = "aws", service, operation, requests = 1, bytesOut = 0, requestCharge, region }) {
+  if (provider === "azure") {
+    return estimateAzureCost({ service, operation, requests, bytesOut, requestCharge, region });
+  }
+  const regionTable = CLOUD_PRICING.aws[region || "us-east-2"] || CLOUD_PRICING.aws["us-east-2"];
   const svc = (service || "").toLowerCase();
   let costUSD = 0;
   let billingUnit = "unknown";
@@ -81,3 +192,47 @@ export function estimateCloudCost({ service, operation, requests = 1, bytesOut =
 
   return { costUSD: parseFloat(costUSD.toFixed(8)), billingUnit };
 }
+
+function estimateAzureCost({ service, operation, requests = 1, bytesOut = 0, requestCharge, region }) {
+  const regionKey   = region || "eastus2";
+  const regionTable = CLOUD_PRICING.azure[regionKey];
+  const svc = (service || "").toLowerCase();
+
+  // Região sem tabela de preço: NÃO cair silenciosamente em eastus2 — um app em
+  // brazilsouth (o caso provável do cliente-alvo) receberia um número de outra
+  // região apresentado como custo dele. Emite o evento com custo nulo e unidade
+  // explícita, pra operação aparecer no relatório sem inventar valor.
+  if (!regionTable) {
+    return { costUSD: null, billingUnit: `${svc || "azure"}-region-unpriced` };
+  }
+
+  let costUSD = 0;
+  let billingUnit = "unknown";
+
+  if (svc === "blob") {
+    const t = regionTable.blob;
+    if (AZURE_BLOB_ITERATOR_OPS.includes(operation)) {
+      costUSD += requests * t.list;
+      billingUnit = "blob-list";
+    } else {
+      const kind = AZURE_BLOB_OPS[operation]?.kind;
+      if (kind === "write")      { costUSD += requests * t.write; billingUnit = "blob-write"; }
+      else if (kind === "read")  { costUSD += requests * t.read;  billingUnit = "blob-read"; }
+      else if (kind === "free")  { billingUnit = "blob-free"; }
+      else                       { costUSD += requests * t.read;  billingUnit = "blob-other"; }
+    }
+    if (bytesOut > 0) costUSD += (bytesOut / GB) * t.transferOutPerGB;
+  } else if (svc === "cosmosdb") {
+    const t = regionTable.cosmosdb;
+    if (typeof requestCharge === "number" && requestCharge > 0) {
+      costUSD = requestCharge * (t.perMillionRU / 1_000_000);
+      billingUnit = "cosmos-ru";
+    } else {
+      const ru = COSMOS_WRITE_SUFFIX.test(operation || "") ? COSMOS_FALLBACK_RU.write : COSMOS_FALLBACK_RU.read;
+      costUSD = requests * ru * (t.perMillionRU / 1_000_000);
+      billingUnit = "cosmos-ru-est";
+    }
+  }
+
+  return { costUSD: parseFloat(costUSD.toFixed(10)), billingUnit };
+}

package/src/test-azure-real.js

@@ -0,0 +1,169 @@
+/**
+ * Teste do wrapAzure contra as classes REAIS do @azure/storage-blob e
+ * @azure/cosmos — não contra fakes escritas à mão.
+ *
+ * Por que existe: os testes de `test.js` usam classes falsas cujo formato foi
+ * desenhado pra casar com a implementação, então não têm como reprovar uma
+ * suposição errada sobre o SDK de verdade (nome de construtor, método em
+ * prototype vs. own property, objeto congelado, fábrica cacheada). Este
+ * arquivo exercita a cadeia real.
+ *
+ * Não faz chamada de rede: usa credencial sintética e só verifica a estrutura
+ * (o que sobrevive à mutação in-place). Calibração de PREÇO contra fatura real
+ * continua pendente — ver README.
+ *
+ * Execute: node src/test-azure-real.js
+ */
+import assert from "node:assert";
+import { BlobServiceClient } from "@azure/storage-blob";
+import { CosmosClient } from "@azure/cosmos";
+import { CloudBrokerCloud } from "./cloud-wrapper.js";
+import {
+  AZURE_BLOB_OPS,
+  AZURE_BLOB_ITERATOR_OPS,
+  AZURE_COSMOS_ITEMS_OPS,
+  AZURE_COSMOS_ITEMS_ITERATOR_OPS,
+} from "./pricing-cloud.js";
+
+let ok = 0, fail = 0;
+const t = (name, fn) => {
+  try { fn(); console.log(`✅ ${name}`); ok++; }
+  catch (e) { console.error(`❌ ${name}\n   ${e.message}`); fail++; }
+};
+
+// Credenciais sintéticas — nenhuma chamada de rede é feita neste arquivo.
+const BLOB_CONN   = "DefaultEndpointsProtocol=https;AccountName=cbtest;AccountKey=dGVzdA==;EndpointSuffix=core.windows.net";
+const COSMOS_CONN = "AccountEndpoint=https://cbtest.documents.azure.com:443/;AccountKey=dGVzdA==;";
+
+console.log("🧪 wrapAzure contra o SDK real da Azure (sem rede)\n");
+
+// ── Blob ─────────────────────────────────────────────────────────────────────
+const rawBlob = BlobServiceClient.fromConnectionString(BLOB_CONN);
+
+t("nomes de construtor reais batem com a tabela de detecção", () => {
+  assert.strictEqual(rawBlob.constructor.name, "BlobServiceClient");
+  assert.strictEqual(rawBlob.getContainerClient("c").constructor.name, "ContainerClient");
+  assert.strictEqual(rawBlob.getContainerClient("c").getBlockBlobClient("b").constructor.name, "BlockBlobClient");
+});
+
+const blobSvc = CloudBrokerCloud.wrapAzure(rawBlob, { apiKey: "cb-test-key" });
+
+t("wrapAzure reconhece o BlobServiceClient real (não caiu no no-op)", () => {
+  assert.strictEqual(blobSvc.__cbWrapped, true, "client real deveria ter sido embrulhado");
+});
+
+t("cadeia de fábricas real sobrevive à mutação in-place", () => {
+  const container = blobSvc.getContainerClient("docs");
+  assert.strictEqual(container.__cbWrapped, true, "ContainerClient devolvido deve vir embrulhado");
+  const blob = container.getBlockBlobClient("nf.pdf");
+  assert.strictEqual(blob.__cbWrapped, true, "BlockBlobClient devolvido deve vir embrulhado");
+});
+
+t("todo método precificado existe em algum client real (nenhuma entrada morta)", () => {
+  const container = rawBlob.getContainerClient("docs");
+  // appendBlock só existe em AppendBlobClient e uploadPages só em PageBlobClient —
+  // achado real deste teste: a tabela precificava os dois, mas checar só o
+  // BlockBlobClient dava falso negativo.
+  const clients = [
+    rawBlob, container,
+    container.getBlockBlobClient("nf.pdf"),
+    container.getAppendBlobClient("log.txt"),
+    container.getPageBlobClient("disk.vhd"),
+  ];
+  const ausentes = Object.keys(AZURE_BLOB_OPS).filter(
+    op => !clients.some(c => typeof c[op] === "function"),
+  );
+  assert.strictEqual(ausentes.length, 0, `métodos precificados que não existem no SDK: ${ausentes.join(", ")}`);
+});
+
+t("AppendBlobClient e PageBlobClient reais também vêm embrulhados", () => {
+  const container = blobSvc.getContainerClient("docs");
+  assert.strictEqual(container.getAppendBlobClient("log.txt").__cbWrapped, true);
+  assert.strictEqual(container.getPageBlobClient("disk.vhd").__cbWrapped, true);
+});
+
+t("métodos de list precificados existem mesmo no SDK real", () => {
+  const container = rawBlob.getContainerClient("docs");
+  const ausentes = AZURE_BLOB_ITERATOR_OPS.filter(
+    op => typeof container[op] !== "function" && typeof rawBlob[op] !== "function",
+  );
+  assert.strictEqual(ausentes.length, 0, `list precificado que não existe: ${ausentes.join(", ")}`);
+});
+
+t("embrulhar não quebra métodos não rastreados do client real", () => {
+  const container = blobSvc.getContainerClient("docs");
+  // getBlobClient/url são API pública que o cliente usa e não rastreamos
+  assert.strictEqual(typeof container.url, "string");
+  assert.strictEqual(typeof container.getBlobClient("x").url, "string");
+});
+
+t("iterator real de listBlobsFlat é lazy (nenhuma rede na criação)", () => {
+  const it = blobSvc.getContainerClient("docs").listBlobsFlat();
+  // Se fosse eager, isto já teria tentado resolver DNS/HTTP e lançado.
+  assert.strictEqual(typeof it.next, "function");
+  assert.strictEqual(typeof it.byPage, "function");
+});
+
+// ── Cosmos ───────────────────────────────────────────────────────────────────
+const rawCosmos = new CosmosClient(COSMOS_CONN);
+
+t("nomes de construtor reais do Cosmos batem", () => {
+  assert.strictEqual(rawCosmos.constructor.name, "CosmosClient");
+  assert.strictEqual(rawCosmos.database("d").constructor.name, "Database");
+  assert.strictEqual(rawCosmos.database("d").container("c").constructor.name, "Container");
+  assert.strictEqual(rawCosmos.database("d").container("c").item("i", "pk").constructor.name, "Item");
+});
+
+t("Database e Container REAIS têm read/delete (motivo de discriminar o nó)", () => {
+  const db = rawCosmos.database("d");
+  const ct = db.container("c");
+  assert.strictEqual(typeof db.read, "function", "Database.read existe — não pode virar item.read");
+  assert.strictEqual(typeof ct.read, "function", "Container.read existe — não pode virar item.read");
+  assert.strictEqual(typeof ct.delete, "function");
+});
+
+const cosmos = CloudBrokerCloud.wrapAzure(rawCosmos, { apiKey: "cb-test-key" });
+
+t("wrapAzure reconhece o CosmosClient real", () => {
+  assert.strictEqual(cosmos.__cbWrapped, true);
+});
+
+t("cadeia real database → container → item vem embrulhada", () => {
+  const db = cosmos.database("loja");
+  assert.strictEqual(db.__cbWrapped, true);
+  const ct = db.container("pedidos");
+  assert.strictEqual(ct.__cbWrapped, true);
+  assert.strictEqual(ct.item("1", "pk").__cbWrapped, true);
+});
+
+t("container.items real é a mesma referência (getter cacheado) e foi embrulhado", () => {
+  const ct = cosmos.database("loja").container("pedidos");
+  assert.strictEqual(ct.items, ct.items, "items deve ser estável entre acessos");
+  assert.strictEqual(ct.items.__cbWrapped, true);
+});
+
+t("métodos de items que a tabela rastreia existem mesmo no SDK real", () => {
+  const items = rawCosmos.database("d").container("c").items;
+  const esperados = [...Object.keys(AZURE_COSMOS_ITEMS_OPS), ...Object.keys(AZURE_COSMOS_ITEMS_ITERATOR_OPS)];
+  const ausentes = esperados.filter(op => typeof items[op] !== "function");
+  assert.strictEqual(ausentes.length, 0, `métodos rastreados que não existem: ${ausentes.join(", ")}`);
+});
+
+t("query() real devolve QueryIterator com fetchAll/fetchNext", () => {
+  const it = cosmos.database("loja").container("pedidos").items.query("SELECT * FROM c");
+  assert.strictEqual(typeof it.fetchAll, "function");
+  assert.strictEqual(typeof it.fetchNext, "function");
+});
+
+t("segundo wrapAzure no mesmo client não re-embrulha", () => {
+  const warns = [];
+  const orig = console.warn;
+  console.warn = (...a) => warns.push(a.join(" "));
+  const again = CloudBrokerCloud.wrapAzure(cosmos, { apiKey: "cb-test-key" });
+  console.warn = orig;
+  assert.strictEqual(again, cosmos);
+  assert.ok(warns.some(w => w.includes("já foi embrulhado")), "deve avisar sobre double-wrap");
+});
+
+console.log(`\n${fail === 0 ? "🎉 TODOS PASSARAM" : "💥 FALHAS"}: ${ok} ok, ${fail} fail`);
+process.exitCode = fail === 0 ? 0 : 1;

package/src/test.js

@@ -225,5 +225,269 @@ await new Promise((r) => setTimeout(r, 50));
 assert.strictEqual(capturedAi[1].events[0].label, "finops-advisor:root-cause-agent");
 console.log("✅ CloudBrokerAI.wrap: label via contexto cbStore (sem cbLabel explícito)");
 
+// ─── AZURE (wrapAzure — Blob Storage + Cosmos DB) ──────────────────────────────
+console.log("\n☁️  Testando wrapAzure (Blob + Cosmos)...");
+
+// 5) Tabela de preços Azure
+const blobW = estimateCloudCost({ provider: "azure", service: "blob", operation: "uploadData", requests: 1 });
+assert.strictEqual(blobW.billingUnit, "blob-write");
+assert.ok(Math.abs(blobW.costUSD - 0.055 / 10_000) < 1e-12, `blob write veio ${blobW.costUSD}`);
+
+const blobR = estimateCloudCost({ provider: "azure", service: "blob", operation: "download", requests: 1, bytesOut: 1024 * 1024 * 1024 });
+assert.strictEqual(blobR.billingUnit, "blob-read");
+assert.ok(Math.abs(blobR.costUSD - (0.0044 / 10_000 + 0.087)) < 1e-9, `blob read+transfer veio ${blobR.costUSD}`);
+
+const blobDel = estimateCloudCost({ provider: "azure", service: "blob", operation: "delete", requests: 1 });
+assert.strictEqual(blobDel.billingUnit, "blob-free");
+assert.strictEqual(blobDel.costUSD, 0);
+
+const blobList = estimateCloudCost({ provider: "azure", service: "blob", operation: "listBlobsFlat", requests: 1 });
+assert.strictEqual(blobList.billingUnit, "blob-list");
+
+const cosmosReal = estimateCloudCost({ provider: "azure", service: "cosmosdb", operation: "items.create", requestCharge: 7.43 });
+assert.strictEqual(cosmosReal.billingUnit, "cosmos-ru");
+assert.ok(Math.abs(cosmosReal.costUSD - 7.43 * 0.25 / 1_000_000) < 1e-15, `cosmos RU real veio ${cosmosReal.costUSD}`);
+
+const cosmosEst = estimateCloudCost({ provider: "azure", service: "cosmosdb", operation: "items.create" });
+assert.strictEqual(cosmosEst.billingUnit, "cosmos-ru-est");
+assert.ok(Math.abs(cosmosEst.costUSD - 5 * 0.25 / 1_000_000) < 1e-15, `cosmos RU fallback veio ${cosmosEst.costUSD}`);
+console.log("✅ estimateCloudCost azure: blob write/read+transfer/delete-free/list, cosmos RU real/fallback");
+
+// 5b) Região sem tabela de preço NÃO pode ser precificada como eastus2 — um app
+// em brazilsouth receberia o custo de outra região apresentado como o dele.
+const brs = estimateCloudCost({ provider: "azure", service: "blob", operation: "uploadData", region: "brazilsouth" });
+assert.strictEqual(brs.costUSD, null, `região sem preço deve dar custo null, veio ${brs.costUSD}`);
+assert.strictEqual(brs.billingUnit, "blob-region-unpriced");
+console.log("✅ região Azure sem tabela: custo null + unidade explícita (não finge eastus2)");
+
+// 6) Blob — cadeia de fábricas, cbLabel não vaza, bytes medidos do argumento certo
+captured.length = 0;
+globalThis.fetch = async (url, opts) => {
+  if (String(url).includes("/api/cloud/events")) captured.push(JSON.parse(opts.body));
+  return { ok: true, status: 200, json: async () => ({}) };
+};
+
+let sawBlobOptions, sawUploadArgs;
+class BlockBlobClient {
+  async uploadData(data, options) { sawBlobOptions = options; return { etag: "0x1" }; }
+  async download() { return { contentLength: 4096 }; }
+  // getProperties devolve o TAMANHO DO BLOB, mas não transfere o blob.
+  async getProperties() { return { contentLength: 5 * 1024 * 1024 * 1024 }; }
+  async uploadBlockBlob(...args) { sawUploadArgs = args; return { etag: "0x2" }; }
+  async setMetadata(meta, options) { return { meta, options }; }
+}
+class ContainerClient {
+  getBlockBlobClient(_name) { return new BlockBlobClient(); }
+  listBlobsFlat() {
+    let i = 0;
+    return { async next() { return i++ < 2 ? { done: false, value: { name: `b${i}` } } : { done: true }; },
+             [Symbol.asyncIterator]() { return this; } };
+  }
+  async uploadBlockBlob(...args) { sawUploadArgs = args; return { etag: "0x2" }; }
+}
+class BlobServiceClient {
+  getContainerClient(_name) { return new ContainerClient(); }
+}
+
+const blobSvc = CloudBrokerCloud.wrapAzure(new BlobServiceClient(), {
+  apiKey: "cb-test-key", product: "checkout", team: "mobile", debug: true,
+});
+const blockBlob = blobSvc.getContainerClient("docs").getBlockBlobClient("nf.pdf");
+const upRes = await blockBlob.uploadData(Buffer.from("hello azure"), { cbLabel: "upload-nf-azure" });
+assert.strictEqual(upRes.etag, "0x1", "resultado original deve ser preservado");
+// O argumento NUNCA é removido: setMetadata() sem argumento apaga os metadados
+// do blob. O options segue existindo, só sem as chaves cb*.
+assert.deepStrictEqual(sawBlobOptions, {}, "options deve chegar sem cb*, mas deve chegar");
+
+const dlRes = await blockBlob.download();
+assert.strictEqual(dlRes.contentLength, 4096);
+
+await new Promise(r => setTimeout(r, 50));
+const azEvents = captured.flatMap(c => c.events);
+assert.strictEqual(azEvents.length, 2, `esperado 2 eventos (upload+download), veio ${azEvents.length}`);
+const [evUp, evDl] = azEvents;
+assert.strictEqual(evUp.provider, "azure");
+assert.strictEqual(evUp.service, "blob");
+assert.strictEqual(evUp.operation, "uploadData");
+assert.strictEqual(evUp.label, "upload-nf-azure");
+assert.strictEqual(evUp.product, "checkout");
+assert.strictEqual(evUp.bytesIn, Buffer.byteLength("hello azure"));
+assert.strictEqual(evUp.billingUnit, "blob-write");
+assert.strictEqual(evDl.operation, "download");
+assert.strictEqual(evDl.bytesOut, 4096);
+assert.strictEqual(evDl.billingUnit, "blob-read");
+console.log("✅ wrapAzure blob: cadeia de fábricas, cb* sem vazar, options preservado, bytes in/out");
+
+// 6b) getProperties NÃO pode cobrar egress do tamanho do blob (custo inflado)
+captured.length = 0;
+await blockBlob.getProperties();
+await new Promise(r => setTimeout(r, 50));
+const evProps = captured.flatMap(c => c.events)[0];
+assert.strictEqual(evProps.operation, "getProperties");
+assert.strictEqual(evProps.bytesOut, 0, `getProperties não transfere o blob; bytesOut veio ${evProps.bytesOut}`);
+assert.ok(evProps.costUSD < 1e-6, `custo de metadado deve ser desprezível, veio ${evProps.costUSD}`);
+console.log("✅ getProperties: sem egress do tamanho do blob (custo de metadado, não de 5 GB)");
+
+// 6c) bytesIn vem do argumento de CORPO declarado, não da primeira string
+// (em uploadBlockBlob a primeira string é o NOME do blob)
+captured.length = 0;
+await blobSvc.getContainerClient("docs").uploadBlockBlob("relatorio-financeiro-2026-07.pdf", Buffer.alloc(10 * 1024 * 1024), 10 * 1024 * 1024);
+await new Promise(r => setTimeout(r, 50));
+const evBlockUp = captured.flatMap(c => c.events)[0];
+assert.strictEqual(evBlockUp.bytesIn, 10 * 1024 * 1024, `bytesIn deve ser o corpo (10MB), veio ${evBlockUp.bytesIn}`);
+console.log("✅ bytesIn: medido do argumento de corpo, não do nome do blob");
+
+// 6d) list é LAZY — nenhum HTTP na criação do iterator. Evento só quando a
+// página é de fato buscada (senão emitia custo de operação que nunca ocorreu).
+captured.length = 0;
+const neverUsed = blobSvc.getContainerClient("docs").listBlobsFlat();
+await new Promise(r => setTimeout(r, 50));
+assert.strictEqual(captured.length, 0, "iterator criado e não consumido não pode gerar custo");
+for await (const _b of neverUsed) { /* consome */ }
+await new Promise(r => setTimeout(r, 50));
+const listEvents = captured.flatMap(c => c.events);
+assert.ok(listEvents.length >= 1, "consumir o iterator deve gerar evento de list");
+assert.strictEqual(listEvents[0].billingUnit, "blob-list");
+console.log("✅ list: sem custo fabricado — evento só quando a página é buscada");
+
+// 7) Cosmos — requestCharge REAL vira custo; iterator de query rastreado
+captured.length = 0;
+let sawCreateArgs;
+class Item {
+  async read() { return { requestCharge: 1.0, resource: { id: "x" } }; }
+}
+class Container {
+  constructor() {
+    this.items = {
+      create: async (...args) => { sawCreateArgs = args; return { requestCharge: 7.43, resource: { id: "y" } }; },
+      query:  (_q) => ({ fetchAll: async () => ({ requestCharge: 3.2, resources: [] }) }),
+      bulk:   async (_ops) => ([{ requestCharge: 5 }, { requestCharge: 6 }]),
+    };
+  }
+  item(_id, _pk) { return new Item(); }
+  // control-plane: lê a definição do CONTAINER, não de um item
+  async read() { return { requestCharge: 2.0, resource: { id: "orders" } }; }
+}
+class Database {
+  container(_id) { return new Container(); }
+  async read() { return { requestCharge: 1.5, resource: { id: "db" } }; }
+}
+class CosmosClient { database(_id) { return new Database(); } }
+
+const cosmos = CloudBrokerCloud.wrapAzure(new CosmosClient(), {
+  apiKey: "cb-test-key", product: "checkout", team: "mobile",
+});
+const cont = cosmos.database("db").container("orders");
+const createRes = await cont.items.create({ id: "y" }, { cbLabel: "criar-pedido" });
+assert.strictEqual(createRes.resource.id, "y");
+await cont.item("x", "pk").read();
+await cont.items.query("SELECT * FROM c").fetchAll();
+
+await new Promise(r => setTimeout(r, 50));
+const cosmosEvents = captured.flatMap(c => c.events);
+assert.strictEqual(cosmosEvents.length, 3, `esperado 3 eventos cosmos, veio ${cosmosEvents.length}`);
+const [evCreate, evRead, evQuery] = cosmosEvents;
+assert.strictEqual(evCreate.service, "cosmosdb");
+assert.strictEqual(evCreate.operation, "items.create");
+assert.strictEqual(evCreate.label, "criar-pedido");
+assert.strictEqual(evCreate.billingUnit, "cosmos-ru");
+assert.ok(Math.abs(evCreate.costUSD - 7.43 * 0.25 / 1_000_000) < 1e-15, `custo RU real veio ${evCreate.costUSD}`);
+assert.strictEqual(evRead.operation, "item.read");
+assert.strictEqual(evQuery.operation, "items.query.fetchAll");
+assert.ok(Math.abs(evQuery.costUSD - 3.2 * 0.25 / 1_000_000) < 1e-15, `custo do query veio ${evQuery.costUSD}`);
+console.log("✅ wrapAzure cosmos: requestCharge real → custo, item.read, query iterator");
+
+// 7b) O DOCUMENTO do cliente nunca é inspecionado nem alterado — um campo
+// chamado cbLabel no corpo tem que ser gravado como veio.
+captured.length = 0;
+const docComCampoColidindo = { id: "z", cbLabel: "campo-de-negocio-do-cliente", valor: 10 };
+await cont.items.create(docComCampoColidindo);
+assert.deepStrictEqual(
+  sawCreateArgs[0],
+  { id: "z", cbLabel: "campo-de-negocio-do-cliente", valor: 10 },
+  "documento do cliente não pode perder campo por colisão de nome",
+);
+await new Promise(r => setTimeout(r, 50));
+assert.strictEqual(captured.flatMap(c => c.events)[0].label, null, "campo do corpo não vira label");
+console.log("✅ documento do cliente intacto: cb* no corpo não é lido nem removido");
+
+// 7c) Container.read()/Database.read() são control-plane — não podem sair
+// rotulados como item.read (operação errada na tela de custo por trecho).
+captured.length = 0;
+await cont.read();
+await cosmos.database("db").read();
+await new Promise(r => setTimeout(r, 50));
+const cpEvents = captured.flatMap(c => c.events);
+assert.strictEqual(cpEvents[0].operation, "container.read", `veio ${cpEvents[0].operation}`);
+assert.strictEqual(cpEvents[1].operation, "database.read", `veio ${cpEvents[1].operation}`);
+console.log("✅ cosmos: container.read/database.read não são confundidos com item.read");
+
+// 7d) bulk soma o requestCharge de cada operação (senão 1000 escritas = 1 leitura)
+captured.length = 0;
+await cont.items.bulk([{ operationType: "Create" }, { operationType: "Create" }]);
+await new Promise(r => setTimeout(r, 50));
+const evBulk = captured.flatMap(c => c.events)[0];
+assert.strictEqual(evBulk.operation, "items.bulk");
+assert.strictEqual(evBulk.billingUnit, "cosmos-ru", "bulk deve usar RU medida, não estimativa");
+assert.ok(Math.abs(evBulk.costUSD - 11 * 0.25 / 1_000_000) < 1e-15, `bulk deve somar 5+6 RU, veio ${evBulk.costUSD}`);
+console.log("✅ cosmos bulk: RUs somadas por operação");
+
+// 8) Robustez — a instrumentação NUNCA pode quebrar a aplicação do cliente.
+// Este é o requisito mais importante: o SDK roda dentro da produção dele.
+captured.length = 0;
+class BlobQuebrado {
+  async uploadData() {
+    // Resposta com propriedade lazy que lança ao ser lida (padrão em SDKs
+    // de streaming). A operação JÁ ACONTECEU no Azure quando isso é lido.
+    return { etag: "ok", get contentLength() { throw new Error("propriedade lazy do SDK lançou"); } };
+  }
+}
+class ContainerQuebrado { getBlockBlobClient() { return new BlobQuebrado(); } }
+class BlobServiceClient2 { getContainerClient() { return new ContainerQuebrado(); } }
+Object.defineProperty(BlobServiceClient2, "name", { value: "BlobServiceClient" });
+Object.defineProperty(ContainerQuebrado, "name", { value: "ContainerClient" });
+Object.defineProperty(BlobQuebrado, "name", { value: "BlockBlobClient" });
+
+const svcQuebrado = CloudBrokerCloud.wrapAzure(new BlobServiceClient2(), { apiKey: "cb-test-key" });
+const r8 = await svcQuebrado.getContainerClient("c").getBlockBlobClient("b").uploadData(Buffer.from("x"));
+assert.strictEqual(r8.etag, "ok", "erro na instrumentação não pode virar erro da aplicação do cliente");
+console.log("✅ robustez: exceção na leitura do resultado não vaza pro app do cliente");
+
+// options com getter que lança, ANTES da chamada real
+class BlobGetterRuim {
+  async uploadData(_d, _o) { return { etag: "ok2" }; }
+}
+Object.defineProperty(BlobGetterRuim, "name", { value: "BlockBlobClient" });
+const bad = CloudBrokerCloud.wrapAzure(new BlobGetterRuim(), { apiKey: "cb-test-key" });
+const optsRuim = Object.defineProperty({}, "cbLabel", { get() { throw new Error("getter ruim"); }, enumerable: true });
+const r8b = await bad.uploadData(Buffer.from("x"), optsRuim);
+assert.strictEqual(r8b.etag, "ok2", "erro ao extrair label não pode impedir a operação real");
+console.log("✅ robustez: falha na extração de label não impede a chamada Azure");
+
+// 8b) Client congelado pelo cliente: a atribuição in-place lançaria (strict
+// mode). Instrumentação nunca pode derrubar a app — avisa e devolve original.
+class BlobCongelado { async uploadData() { return { etag: "frozen-ok" }; } }
+Object.defineProperty(BlobCongelado, "name", { value: "BlockBlobClient" });
+const congelado = Object.freeze(new BlobCongelado());
+const warnsFrozen = [];
+const warnFrozenOrig = console.warn;
+console.warn = (...a) => warnsFrozen.push(a.join(" "));
+const wrappedFrozen = CloudBrokerCloud.wrapAzure(congelado, { apiKey: "cb-test-key" });
+console.warn = warnFrozenOrig;
+const rFrozen = await wrappedFrozen.uploadData(Buffer.from("x"));
+assert.strictEqual(rFrozen.etag, "frozen-ok", "client congelado deve seguir funcionando");
+assert.ok(warnsFrozen.some(w => w.includes("congelado")), "deve avisar que não vai rastrear");
+console.log("✅ robustez: client congelado não quebra a aplicação (avisa e não rastreia)");
+
+// 9) Client não reconhecido → retorna original intocado (e avisa alto)
+class MinhaClasseQualquer { async foo() { return 42; } }
+const warns = [];
+const origWarn = console.warn;
+console.warn = (...a) => warns.push(a.join(" "));
+const untouched = CloudBrokerCloud.wrapAzure(new MinhaClasseQualquer(), { apiKey: "cb-test-key" });
+console.warn = origWarn;
+assert.strictEqual(await untouched.foo(), 42);
+assert.ok(warns.some(w => w.includes("não reconhecido")), "deve avisar mesmo sem debug:true");
+console.log("✅ wrapAzure: client não reconhecido passa intocado, com aviso incondicional");
 globalThis.fetch = realFetch;
 console.log("\n🎉 Todos os testes passaram.");