cloudbroker-sdk 0.2.0 → 0.3.0

package/README.md

@@ -146,6 +146,33 @@ 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.
 
+### Atribuição automática por requisição (Express)
+
+Em vez de passar `cbLabel` em cada `.send()`, use o middleware: todas as chamadas
+de nuvem feitas durante a requisição herdam um label de negócio automaticamente
+(via `AsyncLocalStorage`). Ótimo pra agrupar custo por **módulo** ou **rota**.
+
+```js
+import express from "express";
+import { CloudBrokerCloud } from "cloudbroker-sdk";
+
+const app = express();
+
+// label fixo, "MÉTODO /caminho" (default), ou uma função req → label:
+app.use(CloudBrokerCloud.expressMiddleware({
+  label: (req) => {
+    if (req.path.startsWith("/api/auth"))    return "Autenticação";
+    if (req.path.startsWith("/api/billing")) return "Billing";
+    return "Outros";
+  },
+}));
+
+// daqui pra frente, qualquer s3.send(...)/ddb.send(...) dentro da request
+// é atribuído ao módulo retornado — sem cbLabel manual.
+```
+
+Prioridade do label: `cbLabel` explícito no `.send()` > contexto do middleware > `null`.
+
 ## 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.2.0",
+  "version": "0.3.0",
   "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
   "main": "src/index.js",
   "type": "module",

package/src/client.js

@@ -37,7 +37,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.2.0",
+        sdkVersion: "0.3.0",
         sentAt: new Date().toISOString(),
       };
       if (this.#cloudQueue.length < MAX_QUEUE_SIZE) {
@@ -93,7 +93,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.2.0",
+        sdkVersion: "0.3.0",
         sentAt: new Date().toISOString(),
       };
 

package/src/cloud-wrapper.js

@@ -24,6 +24,7 @@
 
 import { CloudBrokerClient } from "./client.js";
 import { estimateCloudCost } from "./pricing-cloud.js";
+import { cbStore, currentLabel } from "./context.js";
 
 export class CloudBrokerCloud {
   /**
@@ -53,7 +54,9 @@ export class CloudBrokerCloud {
     client.send = async (command, sendOptions) => {
       const start = Date.now();
       const operation = (command?.constructor?.name || "").replace(/Command$/, "");
-      const cbLabel = sendOptions?.cbLabel || null;
+      // Label: explícito no .send() tem prioridade; senão usa o do contexto da
+      // requisição (expressMiddleware), senão null.
+      const cbLabel = sendOptions?.cbLabel || currentLabel() || null;
       const bytesIn = CloudBrokerCloud.#inputBytes(command?.input);
 
       // Passa adiante apenas as options nativas — nunca vaza cbLabel pro AWS SDK.
@@ -91,6 +94,30 @@ export class CloudBrokerCloud {
     return client;
   }
 
+  /**
+   * Middleware Express que atribui um label de negócio a todas as chamadas de
+   * nuvem feitas durante a requisição (via AsyncLocalStorage). Assim o custo por
+   * código agrupa por módulo/rota sem precisar de cbLabel manual em cada send.
+   *
+   * @param {object} [options]
+   * @param {string|((req)=>string)} [options.label] — label fixo, ou função que
+   *   recebe o req e devolve o label (ex: mapear rota → módulo de negócio).
+   *   Default: "MÉTODO /caminho" da requisição.
+   * @returns {(req,res,next)=>void}
+   */
+  static expressMiddleware(options = {}) {
+    const resolve =
+      typeof options.label === "function" ? options.label :
+      typeof options.label === "string"   ? () => options.label :
+      (req) => `${req.method || ""} ${req.baseUrl || ""}${req.route?.path || req.path || ""}`.trim();
+
+    return (req, res, next) => {
+      let label = null;
+      try { label = resolve(req); } catch { label = null; }
+      cbStore.run({ label }, () => next());
+    };
+  }
+
   /** Detecta o serviço AWS pelo nome do construtor do client. */
   static #detectService(client) {
     const name = client?.constructor?.name || "";

package/src/context.js

@@ -0,0 +1,14 @@
+/**
+ * Contexto de requisição via AsyncLocalStorage.
+ * Permite atribuir um label de negócio (módulo / rota) a todas as chamadas de
+ * nuvem disparadas dentro de uma requisição, sem precisar passar cbLabel manual
+ * em cada `.send()`. Server-side apenas (Node).
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const cbStore = new AsyncLocalStorage();
+
+/** Label de negócio do contexto atual, se houver. */
+export function currentLabel() {
+  return cbStore.getStore()?.label || null;
+}

package/src/test.js

@@ -153,5 +153,19 @@ 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");
 
+// 3) expressMiddleware — label do contexto (ALS) entra sem cbLabel explícito
+const mw = CloudBrokerCloud.expressMiddleware({ label: (req) => `modulo:${req.path}` });
+const fakeReq = { method: "GET", path: "/api/billing" };
+await new Promise((resolve) => {
+  mw(fakeReq, {}, async () => {
+    await s3.send(new PutObjectCommand({ Bucket: "b", Key: "k", Body: "x" })); // sem cbLabel — herda do contexto
+    resolve();
+  });
+});
+await new Promise((r) => setTimeout(r, 50));
+const ctxEvent = captured[captured.length - 1].events[0];
+assert.strictEqual(ctxEvent.label, "modulo:/api/billing", `label do contexto esperado, veio ${ctxEvent.label}`);
+console.log("✅ expressMiddleware: label do contexto aplicado sem cbLabel explícito");
+
 globalThis.fetch = realFetch;
 console.log("\n🎉 Todos os testes passaram.");