cloudbroker-sdk 0.4.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;