cloudbroker-sdk 0.5.0 → 0.7.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/pricing.js

@@ -24,9 +24,167 @@ export const PRICING = {
     "claude-3-sonnet-20240229": { input: 0.000003,    output: 0.000015   },
     "claude-3-haiku-20240307":  { input: 0.00000025,  output: 0.00000125 },
   },
+  /**
+   * Gemini — preços do paid tier em ai.google.dev/gemini-api/docs/pricing,
+   * conferidos em 2026-08-02. A página publica por 1M de tokens; aqui, como no
+   * resto da tabela, o valor é por token.
+   *
+   * A conta do Gemini tem três particularidades que um par `{input, output}`
+   * plano não expressa — ignorar qualquer uma delas erra o custo de verdade:
+   *
+   *  - `cached`     — prompt servido de cache custa ~10x menos. Atenção:
+   *                   `promptTokenCount` JÁ INCLUI os tokens cacheados, então o
+   *                   input a preço cheio é `prompt - cached`. Cobrar o prompt
+   *                   inteiro a preço cheio superfatura em 10x essa parcela.
+   *  - `audioInput` — áudio na entrada custa mais que texto/imagem/vídeo nos
+   *                   Flash e Flash-Lite. A separação sai de
+   *                   `promptTokensDetails[].modality === "AUDIO"`.
+   *  - `tierOver`   — o 2.5 Pro dobra acima de 200k tokens de prompt.
+   *
+   * Os modelos 1.5/2.0 que existiam aqui foram removidos: a página oficial não
+   * os lista mais, e manter preço não verificável é fabricar custo. Eles caem
+   * agora no caminho de modelo desconhecido (`costUSD: null`), que é honesto.
+   *
+   * Thinking tokens não aparecem nesta tabela porque não têm preço próprio —
+   * a página diz "Output price (including thinking tokens)", ou seja, são
+   * cobrados como output. Quem soma é `priceGemini()`.
+   */
   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  },
+    "gemini-3.6-flash":      { input: 0.0000015,  output: 0.0000075, cached: 0.00000015 },
+    "gemini-3.5-flash":      { input: 0.0000015,  output: 0.000009,  cached: 0.00000015 },
+    "gemini-3.5-flash-lite": { input: 0.0000003,  output: 0.0000025, cached: 0.00000003 },
+    "gemini-3.1-flash-lite": {
+      input: 0.00000025, output: 0.0000015, cached: 0.000000025,
+      audioInput: 0.0000005, audioCached: 0.00000005,
+    },
+    "gemini-2.5-pro": {
+      input: 0.00000125, output: 0.00001, cached: 0.000000125,
+      tierOver: {
+        promptTokens: 200000,
+        input: 0.0000025, output: 0.000015, cached: 0.00000025,
+      },
+    },
+    "gemini-2.5-flash": {
+      input: 0.0000003, output: 0.0000025, cached: 0.00000003,
+      audioInput: 0.000001, audioCached: 0.0000001,
+    },
+    "gemini-2.5-flash-lite": {
+      input: 0.0000001, output: 0.0000004, cached: 0.00000001,
+      audioInput: 0.0000003, audioCached: 0.00000003,
+    },
   },
 };
+
+/**
+ * Resolve a entrada de preço de um modelo Gemini.
+ *
+ * A API devolve `modelVersion` que muitas vezes carrega sufixo (`-preview-…`,
+ * data). Exigir igualdade exata deixaria quase toda resposta real sem preço;
+ * casar por prefixo sem avisar seria afirmar que preview custa o mesmo que GA,
+ * o que não é garantido. Então: exato é exato, prefixo é marcado `approx`, e o
+ * que não casa não recebe preço de outro modelo.
+ *
+ * @returns {{ id: string, rates: object, approx: boolean } | null}
+ */
+function resolveGeminiModel(model) {
+  if (!model) return null;
+  const table = PRICING.gemini;
+  if (table[model]) return { id: model, rates: table[model], approx: false };
+
+  // Prefixo mais longo primeiro: "gemini-3.5-flash-lite" tem que ganhar de
+  // "gemini-3.5-flash" para "gemini-3.5-flash-lite-preview-01".
+  const match = Object.keys(table)
+    .filter(id => model.startsWith(id))
+    .sort((a, b) => b.length - a.length)[0];
+
+  return match ? { id: match, rates: table[match], approx: true } : null;
+}
+
+/**
+ * Calcula o custo de uma chamada Gemini a partir do `usageMetadata` da resposta.
+ *
+ * Nomes de campo conferidos nos tipos do @google/genai@2.15.0 — a doc pública
+ * mostra um formato snake_case (`total_input_tokens`) que é de outra superfície
+ * da API; o `generateContent` devolve camelCase.
+ *
+ * @param {string} model — `modelVersion` da resposta, ou o pedido na chamada
+ * @param {object} usage — `response.usageMetadata`
+ * @returns {{
+ *   costUSD: number|null, inputTokens: number, outputTokens: number,
+ *   totalTokens: number, cachedTokens: number, thoughtsTokens: number,
+ *   audioInputTokens: number, pricedAs: string|null, approxPricing: boolean,
+ *   unpriced: boolean, reason: string|null
+ * }}
+ */
+export function priceGemini(model, usage = {}) {
+  const prompt   = usage.promptTokenCount        || 0;
+  const cached   = usage.cachedContentTokenCount || 0;
+  const output   = usage.candidatesTokenCount    || 0;
+  const thoughts = usage.thoughtsTokenCount      || 0;
+  const toolUse  = usage.toolUsePromptTokenCount || 0;
+
+  // `prompt` já inclui `cached` — o restante é que sai a preço cheio.
+  // Nunca deixar negativo: se a API mudar a semântica, subfaturar em silêncio
+  // é pior do que somar 0.
+  const fullPriceInput = Math.max(0, prompt - cached);
+
+  // Áudio na entrada tem preço próprio em parte dos modelos. O detalhamento
+  // por modalidade se refere ao prompt inteiro (cacheado incluso), então o
+  // recorte de áudio a preço cheio é proporcional ao que não veio de cache.
+  const audioDetail = (usage.promptTokensDetails || [])
+    .find(d => d?.modality === "AUDIO")?.tokenCount || 0;
+  const audioFullPrice = prompt > 0
+    ? Math.round(audioDetail * (fullPriceInput / prompt))
+    : 0;
+  const audioCached = Math.max(0, audioDetail - audioFullPrice);
+
+  const base = {
+    inputTokens:      prompt + toolUse,
+    outputTokens:     output + thoughts,
+    totalTokens:      usage.totalTokenCount || (prompt + output + thoughts + toolUse),
+    cachedTokens:     cached,
+    thoughtsTokens:   thoughts,
+    audioInputTokens: audioDetail,
+  };
+
+  const resolved = resolveGeminiModel(model);
+  if (!resolved) {
+    return {
+      ...base,
+      costUSD:       null,
+      pricedAs:      null,
+      approxPricing: false,
+      unpriced:      true,
+      reason:        `Modelo "${model || "desconhecido"}" não está na tabela de preço do Gemini — tokens registrados, custo não estimado.`,
+    };
+  }
+
+  // O 2.5 Pro troca de faixa pelo tamanho do prompt.
+  let rates = resolved.rates;
+  if (rates.tierOver && prompt > rates.tierOver.promptTokens) {
+    rates = { ...rates, ...rates.tierOver };
+  }
+
+  const textFullPrice = Math.max(0, fullPriceInput - audioFullPrice);
+  const textCached    = Math.max(0, cached - audioCached);
+
+  const costUSD =
+      textFullPrice  * rates.input
+    + audioFullPrice * (rates.audioInput  ?? rates.input)
+    + textCached     * (rates.cached      ?? rates.input)
+    + audioCached    * (rates.audioCached ?? rates.cached ?? rates.input)
+    + toolUse        * rates.input
+    // Thinking tokens são cobrados como output.
+    + (output + thoughts) * rates.output;
+
+  return {
+    ...base,
+    costUSD:       parseFloat(costUSD.toFixed(8)),
+    pricedAs:      resolved.id,
+    approxPricing: resolved.approx,
+    unpriced:      false,
+    reason:        resolved.approx
+      ? `Preço do modelo base "${resolved.id}" aplicado a "${model}" — variante não listada na tabela oficial.`
+      : null,
+  };
+}

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;