cloudbroker-sdk 0.1.0 → 0.2.0

package/README.md

@@ -106,6 +106,46 @@ CloudBrokerAI.trackDeploy("cb-key-xxxx", {
 });
 ```
 
+## Custo de nuvem a nível de código (MVP)
+
+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
+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.
+
+```js
+import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+import { CloudBrokerCloud } from "cloudbroker-sdk";
+
+const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: "us-east-2" }), {
+  apiKey:  "cb-key-xxxx",
+  product: "checkout",
+  team:    "mobile",
+});
+
+// label opcional do trecho, no 2º argumento do .send()
+await s3.send(new PutObjectCommand({ Bucket: "b", Key: "nf.pdf", Body: buf }), {
+  cbLabel: "upload-nota-fiscal",
+});
+```
+
+Funciona igual com DynamoDB:
+
+```js
+import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
+
+const ddb = CloudBrokerCloud.wrapAWS(new DynamoDBClient({ region: "us-east-2" }), {
+  apiKey: "cb-key-xxxx", product: "checkout",
+});
+await ddb.send(new PutItemCommand({ ... }), { cbLabel: "gravar-pedido" });
+```
+
+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.
+
 ## Garantias
 
 - **Fire-and-forget**: se o CloudBroker estiver fora, sua aplicação não é afetada

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudbroker-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
   "main": "src/index.js",
   "type": "module",

package/src/client.js

@@ -3,25 +3,86 @@
  * Fire-and-forget: nunca bloqueia a aplicação do cliente
  */
 
-const DEFAULT_AI_ENDPOINT = "https://api.cloudbroker.app.br/api/ai/events";
-const DEFAULT_API_BASE    = "https://api.cloudbroker.app.br/api";
-const RETRY_DELAY_MS      = 30_000; // 30s entre retries
-const MAX_QUEUE_SIZE      = 500;    // máximo de eventos em memória
+const DEFAULT_AI_ENDPOINT    = "https://api.cloudbroker.app.br/api/ai/events";
+const DEFAULT_CLOUD_ENDPOINT = "https://api.cloudbroker.app.br/api/cloud/events";
+const DEFAULT_API_BASE       = "https://api.cloudbroker.app.br/api";
+const RETRY_DELAY_MS         = 30_000; // 30s entre retries
+const MAX_QUEUE_SIZE         = 500;    // máximo de eventos em memória
 
 export class CloudBrokerClient {
   #apiKey;
   #aiEndpoint;
+  #cloudEndpoint;
   #apiBase;
   #queue = [];
   #flushing = false;
+  #cloudQueue = [];
+  #cloudFlushing = false;
   #debug;
 
-  constructor({ apiKey, endpoint = DEFAULT_AI_ENDPOINT, apiBase = DEFAULT_API_BASE, debug = false } = {}) {
+  constructor({ apiKey, endpoint = DEFAULT_AI_ENDPOINT, cloudEndpoint = DEFAULT_CLOUD_ENDPOINT, apiBase = DEFAULT_API_BASE, debug = false } = {}) {
     if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
-    this.#apiKey    = apiKey;
-    this.#aiEndpoint = endpoint;
-    this.#apiBase    = apiBase;
-    this.#debug     = debug;
+    this.#apiKey        = apiKey;
+    this.#aiEndpoint    = endpoint;
+    this.#cloudEndpoint = cloudEndpoint;
+    this.#apiBase       = apiBase;
+    this.#debug         = debug;
+  }
+
+  /**
+   * Envia um evento de custo de nuvem (atribuição a nível de código)
+   * Fire-and-forget — nunca lança erro para o caller
+   */
+  trackCloud(event) {
+    try {
+      const payload = {
+        ...event,
+        sdkVersion: "0.2.0",
+        sentAt: new Date().toISOString(),
+      };
+      if (this.#cloudQueue.length < MAX_QUEUE_SIZE) {
+        this.#cloudQueue.push(payload);
+      }
+      this.#flushCloud();
+    } catch (err) {
+      if (this.#debug) console.warn("[CloudBroker] trackCloud error:", err.message);
+    }
+  }
+
+  async #flushCloud() {
+    if (this.#cloudFlushing || this.#cloudQueue.length === 0) return;
+    this.#cloudFlushing = true;
+
+    const batch = this.#cloudQueue.splice(0, 50);
+
+    try {
+      const res = await fetch(this.#cloudEndpoint, {
+        method:  "POST",
+        headers: {
+          "Content-Type":      "application/json",
+          "x-cloudbroker-key": this.#apiKey,
+        },
+        body: JSON.stringify({ events: batch }),
+        signal: AbortSignal.timeout(5000),
+      });
+
+      if (!res.ok) {
+        if (this.#debug) console.warn("[CloudBroker] cloud flush failed:", res.status);
+        this.#cloudQueue.unshift(...batch);
+        setTimeout(() => { this.#cloudFlushing = false; this.#flushCloud(); }, RETRY_DELAY_MS);
+        return;
+      }
+
+      if (this.#debug) console.log(`[CloudBroker] flushed ${batch.length} cloud events`);
+    } catch (err) {
+      this.#cloudQueue.unshift(...batch);
+      if (this.#debug) console.warn("[CloudBroker] cloud flush error:", err.message);
+      setTimeout(() => { this.#cloudFlushing = false; this.#flushCloud(); }, RETRY_DELAY_MS);
+      return;
+    }
+
+    this.#cloudFlushing = false;
+    if (this.#cloudQueue.length > 0) this.#flushCloud();
   }
 
   /**
@@ -32,7 +93,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.1.0",
+        sdkVersion: "0.2.0",
         sentAt: new Date().toISOString(),
       };
 
@@ -144,11 +205,15 @@ export class CloudBrokerClient {
     if (this.#queue.length > 0) this.#flush();
   }
 
-  /** Força flush imediato — útil em shutdown */
+  /** Força flush imediato (IA + nuvem) — útil em shutdown */
   async flushSync() {
     while (this.#queue.length > 0) {
       await this.#flush();
       await new Promise(r => setTimeout(r, 100));
     }
+    while (this.#cloudQueue.length > 0) {
+      await this.#flushCloud();
+      await new Promise(r => setTimeout(r, 100));
+    }
   }
 }

package/src/cloud-wrapper.js

@@ -0,0 +1,127 @@
+/**
+ * CloudBrokerCloud — atribuição de custo de nuvem a nível de código (MVP).
+ *
+ * Envolve um client do AWS SDK v3 (S3 / DynamoDB) e, a cada chamada `.send()`,
+ * estima o custo de requests + transferência e envia um evento fire-and-forget
+ * ao backend. Não altera o comportamento do client original.
+ *
+ * Uso:
+ *   import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+ *   import { CloudBrokerCloud } from "cloudbroker-sdk";
+ *
+ *   const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: "us-east-2" }), {
+ *     apiKey: "cb-key-xxx", product: "checkout", team: "mobile",
+ *   });
+ *
+ *   // label opcional do trecho, no 2º argumento do .send()
+ *   await s3.send(new PutObjectCommand({ ... }), { cbLabel: "upload-nota-fiscal" });
+ *
+ * Nota de implementação: interceptamos via override de `client.send` (em vez do
+ * middlewareStack) porque o `cbLabel` passado no 2º argumento do `.send()` não é
+ * lido de forma confiável pelo context do middleware. O override captura tudo —
+ * nome da operação, bytes in/out, latência e label — de forma limpa e testável.
+ */
+
+import { CloudBrokerClient } from "./client.js";
+import { estimateCloudCost } from "./pricing-cloud.js";
+
+export class CloudBrokerCloud {
+  /**
+   * @param {object} client  — instância do AWS SDK v3 (ex: new S3Client())
+   * @param {object} options
+   * @param {string} options.apiKey   — CloudBroker API key
+   * @param {string} [options.product] — nome do produto (ex: "checkout")
+   * @param {string} [options.team]    — nome do squad (ex: "mobile")
+   * @param {string} [options.region="us-east-2"]
+   * @param {string} [options.endpoint] — endpoint de eventos de nuvem (opcional)
+   * @param {boolean} [options.debug=false]
+   */
+  static wrapAWS(client, options = {}) {
+    const { apiKey, product, team, region = "us-east-2", endpoint, debug = false } = options;
+    if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
+
+    if (!client || typeof client.send !== "function") {
+      if (debug) console.warn("[CloudBroker] cliente AWS sem .send() — retornando original.");
+      return client;
+    }
+
+    const cb = new CloudBrokerClient({ apiKey, cloudEndpoint: endpoint, debug });
+    const service = CloudBrokerCloud.#detectService(client);
+    const clientRegion = CloudBrokerCloud.#resolveRegion(client) || region;
+    const originalSend = client.send.bind(client);
+
+    client.send = async (command, sendOptions) => {
+      const start = Date.now();
+      const operation = (command?.constructor?.name || "").replace(/Command$/, "");
+      const cbLabel = sendOptions?.cbLabel || null;
+      const bytesIn = CloudBrokerCloud.#inputBytes(command?.input);
+
+      // Passa adiante apenas as options nativas — nunca vaza cbLabel pro AWS SDK.
+      const { cbLabel: _omit, ...awsOptions } = sendOptions || {};
+      const result = await originalSend(command, Object.keys(awsOptions).length ? awsOptions : undefined);
+
+      try {
+        const bytesOut = CloudBrokerCloud.#outputBytes(result);
+        const { costUSD, billingUnit } = estimateCloudCost({
+          service, operation, requests: 1, bytesOut, region: clientRegion,
+        });
+
+        cb.trackCloud({
+          provider:  "aws",
+          service,
+          operation,
+          product:   product || null,
+          team:      team    || null,
+          label:     cbLabel,
+          requests:  1,
+          bytesIn,
+          bytesOut,
+          costUSD,
+          billingUnit,
+          latencyMs: Date.now() - start,
+          region:    clientRegion,
+        });
+      } catch (err) {
+        if (debug) console.warn("[CloudBroker] trackCloud error:", err.message);
+      }
+
+      return result;
+    };
+
+    return client;
+  }
+
+  /** Detecta o serviço AWS pelo nome do construtor do client. */
+  static #detectService(client) {
+    const name = client?.constructor?.name || "";
+    if (name.startsWith("S3")) return "s3";
+    if (name.startsWith("DynamoDB")) return "dynamodb"; // cobre DynamoDBClient e DynamoDBDocumentClient
+    return "unknown";
+  }
+
+  /** Tenta resolver a região configurada no client (pode ser função async ou string). */
+  static #resolveRegion(client) {
+    const r = client?.config?.region;
+    if (typeof r === "string") return r;
+    return null; // região via provider async não é resolvida no MVP — usa o fallback de options
+  }
+
+  /** Estima bytes de entrada a partir do input do comando (Body do S3, etc). */
+  static #inputBytes(input) {
+    if (!input) return 0;
+    const body = input.Body;
+    if (body == null) return 0;
+    if (typeof body === "string") return Buffer.byteLength(body);
+    if (Buffer.isBuffer(body)) return body.length;
+    if (body instanceof Uint8Array) return body.byteLength;
+    if (typeof input.ContentLength === "number") return input.ContentLength;
+    return 0; // streams não são medidos no MVP
+  }
+
+  /** Estima bytes de saída a partir do resultado (ContentLength de um GetObject, etc). */
+  static #outputBytes(result) {
+    if (!result) return 0;
+    if (typeof result.ContentLength === "number") return result.ContentLength;
+    return 0;
+  }
+}

package/src/index.js

@@ -8,4 +8,6 @@
  */
 
 export { CloudBrokerAI } from "./wrapper.js";
+export { CloudBrokerCloud } from "./cloud-wrapper.js";
 export { CloudBrokerClient } from "./client.js";
+export { estimateCloudCost, CLOUD_PRICING } from "./pricing-cloud.js";

package/src/pricing-cloud.js

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ * Componentes: requests + transferência de dados (armazenamento GB-mês fora do MVP).
+ * Preços em USD. Atualizado: Jun/2026.
+ */
+export const CLOUD_PRICING = {
+  aws: {
+    "us-east-2": {
+      s3: {
+        // por request (preço por unidade — já dividido por 1.000)
+        put: 0.005 / 1000,    // PUT, COPY, POST, LIST
+        get: 0.0004 / 1000,   // GET, SELECT e demais
+        // transferência de dados de saída para a internet — 1ª faixa (simplificado), por GB
+        transferOutPerGB: 0.09,
+      },
+      dynamodb: {
+        // on-demand
+        wru: 1.25 / 1_000_000,  // write request unit
+        rru: 0.25 / 1_000_000,  // read request unit
+      },
+    },
+  },
+};
+
+const GB = 1024 * 1024 * 1024;
+
+// Operações S3 cobradas como PUT-class (mais caras). O resto cai em GET-class.
+const S3_PUT_CLASS = new Set([
+  "PutObject", "CopyObject", "PostObject", "ListObjects", "ListObjectsV2",
+  "ListBuckets", "CreateMultipartUpload", "UploadPart", "CompleteMultipartUpload",
+]);
+
+// Operações DynamoDB cobradas como escrita (WRU). O resto que gera custo cai em leitura (RRU).
+const DDB_WRITE_OPS = new Set([
+  "PutItem", "UpdateItem", "DeleteItem", "BatchWriteItem", "TransactWriteItems",
+]);
+const DDB_READ_OPS = new Set([
+  "GetItem", "Query", "Scan", "BatchGetItem", "TransactGetItems",
+]);
+
+/**
+ * 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.
+ *
+ * @param {object} p
+ * @param {string} p.service    — "s3" | "dynamodb"
+ * @param {string} p.operation  — nome da operação sem o sufixo "Command" (ex: "PutObject")
+ * @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"]
+ * @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"];
+  const svc = (service || "").toLowerCase();
+  let costUSD = 0;
+  let billingUnit = "unknown";
+
+  if (svc === "s3") {
+    const t = regionTable.s3;
+    const isPut = S3_PUT_CLASS.has(operation);
+    costUSD += requests * (isPut ? t.put : t.get);
+    billingUnit = isPut ? "s3-put" : "s3-get";
+    if (bytesOut > 0) {
+      costUSD += (bytesOut / GB) * t.transferOutPerGB;
+    }
+  } else if (svc === "dynamodb") {
+    const t = regionTable.dynamodb;
+    if (DDB_WRITE_OPS.has(operation)) {
+      costUSD += requests * t.wru;
+      billingUnit = "ddb-wru";
+    } else if (DDB_READ_OPS.has(operation)) {
+      costUSD += requests * t.rru;
+      billingUnit = "ddb-rru";
+    } else {
+      billingUnit = "ddb-none"; // control-plane (ex: DescribeTable) — sem custo de request
+    }
+  }
+
+  return { costUSD: parseFloat(costUSD.toFixed(8)), billingUnit };
+}

package/src/test.js

@@ -74,3 +74,84 @@ wrapped.trackDeploy({
   linesRemoved: 30,
 });
 console.log("✅ Deploy trackado (fire-and-forget)");
+
+// ─── CLOUD COST ATTRIBUTION (MVP) ───────────────────────────────────────────────
+import assert from "node:assert";
+import { CloudBrokerCloud } from "./cloud-wrapper.js";
+import { estimateCloudCost } from "./pricing-cloud.js";
+
+console.log("\n☁️  Testando atribuição de custo de nuvem...");
+
+// 1) Tabela de preços / estimativa
+const s3put = estimateCloudCost({ service: "s3", operation: "PutObject", requests: 1 });
+assert.strictEqual(s3put.billingUnit, "s3-put");
+assert.ok(Math.abs(s3put.costUSD - 0.000005) < 1e-9, `s3 put esperado 0.000005, veio ${s3put.costUSD}`);
+
+const s3get = estimateCloudCost({ service: "s3", operation: "GetObject", requests: 1, bytesOut: 1024 * 1024 * 1024 });
+assert.strictEqual(s3get.billingUnit, "s3-get");
+// 0.0000004 (request) + 0.09 (1 GB de transferência)
+assert.ok(Math.abs(s3get.costUSD - 0.0900004) < 1e-6, `s3 get+transfer veio ${s3get.costUSD}`);
+
+const ddbW = estimateCloudCost({ service: "dynamodb", operation: "PutItem", requests: 1 });
+assert.strictEqual(ddbW.billingUnit, "ddb-wru");
+assert.ok(Math.abs(ddbW.costUSD - 0.00000125) < 1e-12, `ddb write veio ${ddbW.costUSD}`);
+
+const ddbR = estimateCloudCost({ service: "dynamodb", operation: "GetItem", requests: 1 });
+assert.strictEqual(ddbR.billingUnit, "ddb-rru");
+assert.ok(Math.abs(ddbR.costUSD - 0.00000025) < 1e-12, `ddb read veio ${ddbR.costUSD}`);
+
+const ddbCtl = estimateCloudCost({ service: "dynamodb", operation: "DescribeTable", requests: 1 });
+assert.strictEqual(ddbCtl.billingUnit, "ddb-none");
+assert.strictEqual(ddbCtl.costUSD, 0);
+console.log("✅ estimateCloudCost: S3 put/get+transfer e DynamoDB wru/rru/control-plane");
+
+// 2) wrapAWS — captura evento, não vaza cbLabel pro AWS, preserva resultado
+const captured = [];
+const realFetch = globalThis.fetch;
+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 () => ({}) };
+  }
+  return { ok: true, status: 200, json: async () => ({}) };
+};
+
+let sawAwsOptions; // o que o "AWS SDK" recebeu de options
+class S3Client {
+  constructor(cfg) { this.config = cfg; }
+  async send(command, options) {
+    sawAwsOptions = options;
+    return { ContentLength: 2048, $metadata: { httpStatusCode: 200 } };
+  }
+}
+class PutObjectCommand {
+  constructor(input) { this.input = input; }
+}
+
+const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: "us-east-2" }), {
+  apiKey: "cb-test-key", product: "checkout", team: "mobile", debug: true,
+});
+
+const putRes = await s3.send(new PutObjectCommand({ Bucket: "b", Key: "k", Body: "hello world" }), { cbLabel: "upload-nf" });
+assert.strictEqual(putRes.ContentLength, 2048, "resultado original deve ser preservado");
+assert.strictEqual(sawAwsOptions, undefined, "cbLabel não pode vazar pro AWS SDK (options ficou só com cbLabel → vira undefined)");
+
+await s3.flushSync?.(); // garante envio
+// pequena espera pro fire-and-forget
+await new Promise(r => setTimeout(r, 50));
+
+assert.strictEqual(captured.length, 1, `esperado 1 evento de nuvem, veio ${captured.length}`);
+const ev = captured[0].events[0];
+assert.strictEqual(ev.provider, "aws");
+assert.strictEqual(ev.service, "s3");
+assert.strictEqual(ev.operation, "PutObject");
+assert.strictEqual(ev.product, "checkout");
+assert.strictEqual(ev.team, "mobile");
+assert.strictEqual(ev.label, "upload-nf");
+assert.strictEqual(ev.bytesIn, Buffer.byteLength("hello world"));
+assert.strictEqual(ev.billingUnit, "s3-put");
+assert.ok(ev.costUSD > 0, "deve ter custo estimado");
+console.log("✅ wrapAWS: evento capturado, cbLabel não vazou, resultado preservado");
+
+globalThis.fetch = realFetch;
+console.log("\n🎉 Todos os testes passaram.");