cloudbroker-sdk 0.2.0 → 0.4.0

package/README.md

@@ -146,6 +146,35 @@ 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**.
+
+Cada campo (`label`, `product`, `team`) pode ser fixo (string) ou uma função
+`(req) => string`. Isso permite a hierarquia **Grupo (team) → App (product) →
+Trecho (label) → Serviço** na visão de custo.
+
+```js
+import express from "express";
+import { CloudBrokerCloud } from "cloudbroker-sdk";
+
+const app = express();
+
+app.use(CloudBrokerCloud.expressMiddleware({
+  team:    (req) => (req.path.startsWith("/api/admin") ? "Plataforma" : "Produto"), // Grupo
+  product: (req) => req.path.split("/")[2] || "core",                              // App
+  label:   (req) => `${req.method} ${req.path}`,                                   // Trecho
+}));
+
+// daqui pra frente, qualquer s3.send(...)/ddb.send(...) dentro da request
+// é atribuído ao grupo/app/trecho — sem cbLabel manual.
+```
+
+Prioridade de cada campo: explícito no `.send()` (`cbLabel`/`cbProduct`/`cbTeam`) >
+contexto do middleware > valor estático do `wrapAWS` > `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.4.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.4.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.4.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 } from "./context.js";
 
 export class CloudBrokerCloud {
   /**
@@ -53,11 +54,16 @@ export class CloudBrokerCloud {
     client.send = async (command, sendOptions) => {
       const start = Date.now();
       const operation = (command?.constructor?.name || "").replace(/Command$/, "");
-      const cbLabel = sendOptions?.cbLabel || null;
+      // Prioridade: explícito no .send() > contexto da requisição (expressMiddleware)
+      // > valor estático do wrapAWS. Permite Grupo/App/Trecho por requisição.
+      const ctx = cbStore.getStore() || {};
+      const cbLabel   = sendOptions?.cbLabel   || ctx.label   || null;
+      const evProduct = sendOptions?.cbProduct || ctx.product || product || null;
+      const evTeam    = sendOptions?.cbTeam    || ctx.team    || team    || null;
       const bytesIn = CloudBrokerCloud.#inputBytes(command?.input);
 
-      // Passa adiante apenas as options nativas — nunca vaza cbLabel pro AWS SDK.
-      const { cbLabel: _omit, ...awsOptions } = sendOptions || {};
+      // Passa adiante apenas as options nativas — nunca vaza campos cb* pro AWS SDK.
+      const { cbLabel: _l, cbProduct: _p, cbTeam: _t, ...awsOptions } = sendOptions || {};
       const result = await originalSend(command, Object.keys(awsOptions).length ? awsOptions : undefined);
 
       try {
@@ -70,8 +76,8 @@ export class CloudBrokerCloud {
           provider:  "aws",
           service,
           operation,
-          product:   product || null,
-          team:      team    || null,
+          product:   evProduct,
+          team:      evTeam,
           label:     cbLabel,
           requests:  1,
           bytesIn,
@@ -91,6 +97,33 @@ export class CloudBrokerCloud {
     return client;
   }
 
+  /**
+   * Middleware Express que atribui contexto de negócio a todas as chamadas de
+   * nuvem feitas durante a requisição (via AsyncLocalStorage). Cada campo pode ser
+   * fixo (string) ou uma função (req) => string — ex: mapear rota → módulo/app/grupo.
+   * Sem precisar passar cbLabel/cbProduct/cbTeam manual em cada send.
+   *
+   * @param {object} [options]
+   * @param {string|((req)=>string)} [options.label]   — trecho (default: "MÉTODO /caminho")
+   * @param {string|((req)=>string)} [options.product] — App (sobrescreve o product do wrapAWS)
+   * @param {string|((req)=>string)} [options.team]    — Grupo (sobrescreve o team do wrapAWS)
+   * @returns {(req,res,next)=>void}
+   */
+  static expressMiddleware(options = {}) {
+    const mk = (opt, fallback) =>
+      typeof opt === "function" ? opt :
+      typeof opt === "string"   ? () => opt :
+      fallback;
+    const resolveLabel   = mk(options.label, (req) => `${req.method || ""} ${req.baseUrl || ""}${req.route?.path || req.path || ""}`.trim());
+    const resolveProduct = mk(options.product, () => undefined);
+    const resolveTeam    = mk(options.team, () => undefined);
+
+    return (req, res, next) => {
+      const safe = (fn) => { try { return fn(req); } catch { return undefined; } };
+      cbStore.run({ label: safe(resolveLabel), product: safe(resolveProduct), team: safe(resolveTeam) }, () => 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,25 @@ 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}`,
+  product: (req) => (req.path.startsWith("/api/billing") ? "Billing" : "Outros"),
+  team:    "Plataforma",
+});
+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 cb* — 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}`);
+assert.strictEqual(ctxEvent.product, "Billing",     `product do contexto esperado, veio ${ctxEvent.product}`);
+assert.strictEqual(ctxEvent.team,    "Plataforma",  `team do contexto esperado, veio ${ctxEvent.team}`);
+console.log("✅ expressMiddleware: label/product/team do contexto aplicados sem cb* explícito");
+
 globalThis.fetch = realFetch;
 console.log("\n🎉 Todos os testes passaram.");