cloudbroker-sdk 0.7.0 → 0.8.1

package/.github/workflows/publish.yml

@@ -1,6 +1,12 @@
 name: Publish to npm
 
 on:
+  # Testar também em PR: até aqui a suíte só rodava no caminho de publish, e
+  # publish só dispara em push no main que toque package.json. Ou seja, um PR
+  # que quebrasse o SDK não era pego por nada — o erro só apareceria na hora
+  # de lançar a versão. Mesmo formato adotado no backend (job `test` rodando
+  # em PR e push, com o job de entrega dependendo dele).
+  pull_request:
   push:
     branches: [main]
     paths:
@@ -16,31 +22,100 @@ on:
   workflow_dispatch:
 
 jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      # Não falha as demais versões quando uma quebra — saber que 24 passa e
+      # 20 não é a informação útil; abortar em cima da primeira esconde isso.
+      fail-fast: false
+      matrix:
+        # Este pacote roda DENTRO da aplicação de produção do cliente, então o
+        # que importa não é "o Node que a gente gosta", é a faixa que o cliente
+        # pode estar rodando.
+        #
+        # 20 é o piso: era a única versão testada até aqui, e sair dela sem
+        # aviso quebraria quem ainda está lá. Está EOL desde março/2026, e é
+        # exatamente por isso que ele não pode ser a ÚNICA — testar só nele
+        # significava nunca exercitar o SDK no Node que os clientes usam hoje.
+        node: [20, 22, 24]
+    name: test (node ${{ matrix.node }})
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Instalar dependências
+        run: npm ci || npm install
+
+      - name: Rodar testes
+        run: npm test
+
   publish:
+    needs: test
+    # Só publica no caminho de release. Sem esta guarda, o gatilho de
+    # pull_request acima tentaria publicar a cada PR.
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
     permissions:
       contents: read
       id-token: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
-          node-version: 20
+          # LTS atual para o artefato publicado. A compatibilidade com as
+          # outras versões é garantida pela matriz do job `test` acima, que
+          # este job exige via `needs`.
+          node-version: 22
           registry-url: 'https://registry.npmjs.org'
 
-      # Gate de teste antes do publish — este pacote roda DENTRO da aplicação
-      # de produção do cliente; publicar sem rodar a suíte já era um risco
-      # aberto (nenhum CI de teste existia neste repo).
-      - name: Instalar dependências de teste
+      - name: Instalar dependências
         run: npm ci || npm install
 
-      - name: Rodar testes
-        run: npm test
+      # Trusted Publishing (OIDC): o npm confia neste workflow pelo token de
+      # identidade do GitHub (permissions.id-token: write acima) — sem NPM_TOKEN
+      # de longa duração. O publish por token falhava com EOTP desde 27/07
+      # (token que exige 2FA), e as versões saíam à mão, pulando a suíte.
+      # Exige npm >= 11.5.1; o Node 22 traz 10.x, e com npm antigo o publish
+      # falha sem dizer por quê. Versão fixa, a mesma do cloudbroker-mcp.
+      # Configuração do lado do npm (uma vez, pelo dono do pacote):
+      #   npm trust github cloudbroker-sdk --file publish.yml \
+      #     --repo cloudbroker-app/cloudbroker-sdk --allow-stage-publish
+      # O gatilho dispara em QUALQUER mudança no package.json, não só em troca
+      # de versão — o merge do PR #17 (só o campo `repository`) tentou
+      # republicar a 0.7.0 e deixou o main vermelho. Se a versão já está no
+      # registro, encerra com aviso. Só pula com confirmação positiva (o npm
+      # devolveu exatamente esta versão): 404 ou falha de rede seguem para o
+      # publish, que falha alto se houver problema de verdade.
+      - name: Versão já publicada?
+        id: published
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+          FOUND=$(npm view "$NAME@$VERSION" version 2>/dev/null || true)
+          if [ "$FOUND" = "$VERSION" ]; then
+            echo "::notice::$NAME@$VERSION já está no npm — nada a publicar (troque a versão para lançar)."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Atualizar npm (OIDC exige >= 11.5.1; npm stage vem no 11.19)
+        if: steps.published.outputs.skip != 'true'
+        run: npm install -g npm@11.19.1 && npm --version
 
-      - name: Publish to npm
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      # Staged publishing: o CI só deixa a versão em STAGING (fora do ar); quem
+      # publica de fato é uma pessoa, com 2FA:
+      #   npm stage list cloudbroker-sdk
+      #   npm stage approve <id-do-staging>
+      # Sem NODE_AUTH_TOKEN: a autenticação vem do OIDC.
+      - name: Stage no npm (aprovação manual com 2FA)
+        if: steps.published.outputs.skip != 'true'
+        run: npm stage publish

package/README.md

@@ -309,6 +309,46 @@ app.use(CloudBrokerCloud.expressMiddleware({
 Prioridade de cada campo: explícito no `.send()` (`cbLabel`/`cbProduct`/`cbTeam`) >
 contexto do middleware > valor estático do `wrapAWS` > `null`.
 
+### Custo por execução e versão do código (0.8.0)
+
+Cada evento do `wrapAWS`/`wrapAzure` é uma **chamada de API**, não uma
+**execução** do trecho. Se o custo de um trecho sobe, só com chamadas não dá
+para saber se o código passou a chamar mais ou se veio mais tráfego. O
+`ExecutionCounter` conta as execuções e fecha essa conta: **custo por
+execução** e **chamadas por execução**.
+
+```js
+import { CloudBrokerCloud, ExecutionCounter } from "cloudbroker-sdk";
+
+const execucoes = new ExecutionCounter({ apiKey: process.env.CLOUDBROKER_API_KEY });
+
+app.use(CloudBrokerCloud.expressMiddleware({
+  product: "checkout",
+  label:   (req) => req.path.split("/").slice(0, 3).join("/"),         // prefixo da rota ("/api/pedidos"), sem ids
+  executions: execucoes,                                               // 1 execução por requisição
+}));
+
+// Fora do Express (jobs, filas, workers):
+await CloudBrokerCloud.trackExecution("job:fechamento-mensal", () => fecharMes(), {
+  product: "financeiro", executions: execucoes,
+});
+```
+
+- A contagem fica em memória, agregada por trecho, app, versão e hora, e sai
+  em lote a cada 60 s (`flushIntervalMs`). Nada de rede no caminho da
+  requisição; o timer não segura o processo.
+- **Use rótulo de baixa cardinalidade.** Um rótulo com id (`/api/pedidos/123`)
+  cria uma combinação por pedido; acima de 200 combinações pendentes o
+  excedente é descartado e somado em `execucoes.dropped`. O rótulo padrão do
+  middleware é o caminho cru — com `executions`, passe sempre um `label`.
+  (Middleware de `app.use` roda antes do roteamento: `req.route` ainda não
+  existe nele.)
+- **Versão do código:** defina `CLOUDBROKER_VERSION` (ex.: o `GIT_SHA` do
+  build) ou passe `version` ao `ExecutionCounter` e ao `wrapAWS`/`wrapAzure`.
+  Ela vai nas execuções e nas chamadas, para comparar o trecho antes e depois
+  de um deploy pela versão que de fato rodou.
+- No shutdown: `await execucoes.flush(); execucoes.stop();`.
+
 ## Garantias
 
 - **Fire-and-forget**: se o CloudBroker estiver fora, sua aplicação não é afetada

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "cloudbroker-sdk",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudbroker-app/cloudbroker-sdk.git"
+  },
   "main": "src/index.js",
   "type": "module",
   "exports": {
     ".": "./src/index.js"
   },
   "scripts": {
-    "test": "node src/test.js && node src/test-azure-real.js && node src/test-gemini-real.js"
+    "test": "node src/test.js && node src/test-executions.js && node src/test-azure-real.js && node src/test-gemini-real.js"
   },
   "keywords": [
     "cloudbroker",

package/src/client.js

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

package/src/cloud-wrapper.js

@@ -36,6 +36,7 @@ import {
   AZURE_COSMOS_ITEMS_ITERATOR_OPS,
 } from "./pricing-cloud.js";
 import { cbStore } from "./context.js";
+import { resolveVersion } from "./executions.js";
 
 // Nomes de construtor do @azure/* → tipo do nó na cadeia de sub-clients.
 const AZURE_BLOB_KIND = {
@@ -149,10 +150,12 @@ export class CloudBrokerCloud {
    * @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 {string} [options.version] — versão do código (padrão: env CLOUDBROKER_VERSION, ex.: o GIT_SHA do build)
    * @param {boolean} [options.debug=false]
    */
   static wrapAWS(client, options = {}) {
     const { apiKey, product, team, region = "us-east-2", endpoint, debug = false } = options;
+    const version = resolveVersion(options.version);
     if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
 
     if (!client || typeof client.send !== "function") {
@@ -200,6 +203,7 @@ export class CloudBrokerCloud {
           billingUnit,
           latencyMs: Date.now() - start,
           region:    clientRegion,
+          version,
         });
       } catch (err) {
         if (debug) console.warn("[CloudBroker] trackCloud error:", err.message);
@@ -221,6 +225,9 @@ export class CloudBrokerCloud {
    * @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)
+   * @param {import("./executions.js").ExecutionCounter} [options.executions] — se informado,
+   *   conta UMA execução do trecho por requisição (custo por execução, Passo 2).
+   *   Use rótulo de baixa cardinalidade (módulo/rota com padrão), nunca o caminho cru com ids.
    * @returns {(req,res,next)=>void}
    */
   static expressMiddleware(options = {}) {
@@ -232,12 +239,38 @@ export class CloudBrokerCloud {
     const resolveProduct = mk(options.product, () => undefined);
     const resolveTeam    = mk(options.team, () => undefined);
 
+    const executions = options.executions;
+
     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());
+      const ctx = { label: safe(resolveLabel), product: safe(resolveProduct), team: safe(resolveTeam) };
+      try {
+        if (executions && typeof executions.count === "function") executions.count(ctx);
+      } catch { /* contador nunca derruba a requisição */ }
+      cbStore.run(ctx, () => next());
     };
   }
 
+  /**
+   * Roda `fn` como UMA execução do trecho `label`, para código fora do
+   * Express (jobs, filas, workers): as chamadas de nuvem/IA feitas dentro de
+   * `fn` herdam o trecho (mesmo contexto do expressMiddleware) e, com
+   * `options.executions`, a execução é contada. Devolve o que `fn` devolver
+   * (inclusive a Promise) e propaga o erro de `fn` — a instrumentação em si
+   * nunca lança.
+   *
+   * @param {string} label — trecho (baixa cardinalidade, ex.: "job:fechamento")
+   * @param {Function} fn
+   * @param {{product?: string, team?: string, executions?: import("./executions.js").ExecutionCounter}} [options]
+   */
+  static trackExecution(label, fn, options = {}) {
+    const ctx = { label, product: options.product, team: options.team };
+    try {
+      if (options.executions && typeof options.executions.count === "function") options.executions.count(ctx);
+    } catch { /* contador nunca derruba a execução */ }
+    return cbStore.run(ctx, fn);
+  }
+
   /**
    * Envolve um client do Azure SDK (Blob Storage / Cosmos DB) e rastreia cada
    * chamada de data-plane como evento de custo — mesmo contrato do wrapAWS.
@@ -272,6 +305,7 @@ export class CloudBrokerCloud {
    */
   static wrapAzure(client, options = {}) {
     const { apiKey, product, team, region = "eastus2", endpoint, debug = false } = options;
+    const version = resolveVersion(options.version);
     if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
 
     const name = client?.constructor?.name || "";
@@ -295,7 +329,7 @@ export class CloudBrokerCloud {
     }
 
     const cb  = new CloudBrokerClient({ apiKey, cloudEndpoint: endpoint, debug });
-    const env = { cb, product, team, region, debug };
+    const env = { cb, product, team, region, debug, version };
     return blobKind
       ? CloudBrokerCloud.#wrapBlobNode(client, env)
       : CloudBrokerCloud.#wrapCosmosNode(client, env, cosmosKind);
@@ -348,6 +382,7 @@ export class CloudBrokerCloud {
         billingUnit,
         latencyMs,
         region:    env.region,
+        version:   env.version,
       });
     } catch (err) {
       if (env.debug) console.warn("[CloudBroker] trackCloud error:", err.message);

package/src/executions.js

@@ -0,0 +1,152 @@
+/**
+ * ExecutionCounter — contador de EXECUÇÕES de trecho de código (0.8.0).
+ *
+ * Por que existe: o wrapAWS/wrapAzure grava um evento por CHAMADA de API, não
+ * por execução do trecho. Sem o número de execuções, "o código passou a chamar
+ * mais" e "veio mais tráfego" são indistinguíveis — o custo por chamada é
+ * quase constante por construção. Este contador é o denominador que separa os
+ * dois (custo por execução, chamadas por execução).
+ *
+ * Como: contagem EM MEMÓRIA, agregada por (trecho, app, versão, hora UTC), e
+ * enviada em lote a cada `flushIntervalMs` para POST /api/cloud/executions.
+ * Uma requisição = uma soma num Map; nada de rede no caminho da aplicação.
+ *
+ * Garantias (iguais às do resto do SDK):
+ *   • nunca lança para a aplicação do cliente;
+ *   • timer com `.unref()` — não segura o processo (Lambda, cron, CLI);
+ *   • memória limitada: no máximo `maxKeys` combinações pendentes; o excedente
+ *     é descartado e contado em `dropped` (rótulo de alta cardinalidade, como
+ *     uma rota com id no caminho, não pode crescer sem limite);
+ *   • contagem com mais de 7 dias sem conseguir enviar é descartada (o backend
+ *     recusa, e reenviar para sempre seria inútil).
+ *
+ * Uso:
+ *   const execucoes = new ExecutionCounter({ apiKey: "cb-key-xxx" }); // version ← CLOUDBROKER_VERSION
+ *   app.use(CloudBrokerCloud.expressMiddleware({ label: ..., executions: execucoes }));
+ *   await CloudBrokerCloud.trackExecution("job:fechamento", () => fecharMes(), { executions: execucoes });
+ */
+
+const DEFAULT_EXECUTIONS_ENDPOINT = "https://api.cloudbroker.app.br/api/cloud/executions";
+const HOUR_MS = 3_600_000;
+const MAX_AGE_MS = 7 * 24 * HOUR_MS;
+
+/** Versão do código do cliente: explícita > CLOUDBROKER_VERSION > null. */
+export function resolveVersion(explicit) {
+  const v = typeof explicit === "string" && explicit.trim() ? explicit
+    : (typeof process !== "undefined" ? process.env?.CLOUDBROKER_VERSION : undefined);
+  return typeof v === "string" && v.trim() ? v.trim().slice(0, 64) : null;
+}
+
+function hourStartIso(ms) {
+  return new Date(Math.floor(ms / HOUR_MS) * HOUR_MS).toISOString();
+}
+
+export class ExecutionCounter {
+  #apiKey;
+  #endpoint;
+  #version;
+  #debug;
+  #maxKeys;
+  #now;
+  #pending = new Map();
+  #flushing = false;
+  #timer = null;
+  dropped = 0;
+
+  /**
+   * @param {object} options
+   * @param {string} options.apiKey — API key CloudBroker do tipo SDK
+   * @param {string} [options.version] — versão do código (padrão: CLOUDBROKER_VERSION)
+   * @param {string} [options.endpoint]
+   * @param {number} [options.flushIntervalMs=60000]
+   * @param {number} [options.maxKeys=200] — o backend recusa lote com mais de 200
+   * @param {boolean} [options.debug=false]
+   */
+  constructor({ apiKey, version, endpoint = DEFAULT_EXECUTIONS_ENDPOINT, flushIntervalMs = 60_000, maxKeys = 200, debug = false, now } = {}) {
+    if (!apiKey) throw new Error("[CloudBroker] apiKey é obrigatório.");
+    this.#apiKey = apiKey;
+    this.#endpoint = endpoint;
+    this.#version = resolveVersion(version);
+    this.#debug = debug;
+    this.#maxKeys = Math.max(1, Math.min(200, Math.floor(maxKeys) || 200));
+    this.#now = typeof now === "function" ? now : Date.now;
+    if (flushIntervalMs > 0) {
+      this.#timer = setInterval(() => { this.flush(); }, flushIntervalMs);
+      if (typeof this.#timer?.unref === "function") this.#timer.unref();
+    }
+  }
+
+  /** Versão que este contador anexa às execuções. */
+  get version() { return this.#version; }
+
+  /** Combinações pendentes de envio (para diagnóstico/teste). */
+  get pendingKeys() { return this.#pending.size; }
+
+  /**
+   * Soma uma execução do trecho. Nunca lança.
+   * @param {{label?: string, product?: string}} ctx
+   */
+  count(ctx) {
+    try {
+      const label = ctx?.label, product = ctx?.product;
+      if (typeof label !== "string" || !label.trim()) return;
+      const hour = hourStartIso(this.#now());
+      const prod = typeof product === "string" && product.trim() ? product : null;
+      const key = `${hour}\u0000${label}\u0000${prod || ""}`;
+      const cur = this.#pending.get(key);
+      if (cur) { cur.count++; return; }
+      if (this.#pending.size >= this.#maxKeys) { this.dropped++; return; }
+      this.#pending.set(key, { label, product: prod, version: this.#version, hour, count: 1 });
+    } catch (err) {
+      if (this.#debug) console.warn("[CloudBroker] executions.count error:", err.message);
+    }
+  }
+
+  /** Envia o pendente. Nunca lança; em falha transitória, a contagem volta para a fila. */
+  async flush() {
+    if (this.#flushing || this.#pending.size === 0) return;
+    this.#flushing = true;
+    const batch = [...this.#pending.values()];
+    this.#pending = new Map();
+    let devolver = false;
+    try {
+      const res = await fetch(this.#endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "x-cloudbroker-key": this.#apiKey },
+        body: JSON.stringify({ executions: batch }),
+        signal: AbortSignal.timeout(5000),
+      });
+      if (!res.ok) {
+        // 4xx (exceto 429) é recusa definitiva — reenviar o mesmo lote não muda nada.
+        devolver = res.status === 429 || res.status >= 500;
+        if (this.#debug) console.warn(`[CloudBroker] executions flush failed: ${res.status}${devolver ? " (vai tentar de novo)" : " (descartado)"}`);
+      } else if (this.#debug) {
+        console.log(`[CloudBroker] flushed ${batch.length} execution buckets`);
+      }
+    } catch (err) {
+      devolver = true;
+      if (this.#debug) console.warn("[CloudBroker] executions flush error:", err.message);
+    } finally {
+      if (devolver) this.#requeue(batch);
+      this.#flushing = false;
+    }
+  }
+
+  #requeue(batch) {
+    const limite = this.#now() - MAX_AGE_MS;
+    for (const it of batch) {
+      if (Date.parse(it.hour) < limite) { this.dropped += it.count; continue; }
+      const key = `${it.hour}\u0000${it.label}\u0000${it.product || ""}`;
+      const cur = this.#pending.get(key);
+      if (cur) cur.count += it.count;
+      else if (this.#pending.size < this.#maxKeys) this.#pending.set(key, it);
+      else this.dropped += it.count;
+    }
+  }
+
+  /** Para o timer (ex.: no shutdown, depois de um `await flush()`). */
+  stop() {
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = null;
+  }
+}

package/src/index.js

@@ -10,4 +10,5 @@
 export { CloudBrokerAI } from "./wrapper.js";
 export { CloudBrokerCloud } from "./cloud-wrapper.js";
 export { CloudBrokerClient } from "./client.js";
+export { ExecutionCounter } from "./executions.js";
 export { estimateCloudCost, CLOUD_PRICING } from "./pricing-cloud.js";

package/src/pricing.js

@@ -1,7 +1,7 @@
 /**
  * Tabela de preços por provider/modelo
  * Preços em USD por token
- * Atualizado: Mai/2026
+ * Atualizado: Mai/2026 (Anthropic conferida em Out/2026)
  */
 export const PRICING = {
   openai: {
@@ -16,10 +16,13 @@ export const PRICING = {
     "text-embedding-3-large":   { input: 0.00000013,  output: 0          },
   },
   anthropic: {
-    "claude-opus-4-6":          { input: 0.000015,    output: 0.000075   },
+    // Conferidos em 2026-10-12 contra a tabela oficial da Anthropic. Até essa
+    // data o Haiku 4.5 estava com o preço do Haiku 3 (4x abaixo do real) e o
+    // Opus 4.6 com o do Opus 4/4.1 (3x acima).
+    "claude-opus-4-6":          { input: 0.000005,    output: 0.000025   },
     "claude-sonnet-4-6":        { input: 0.000003,    output: 0.000015   },
     "claude-sonnet-4-5":        { input: 0.000003,    output: 0.000015   },
-    "claude-haiku-4-5-20251001":{ input: 0.00000025,  output: 0.00000125 },
+    "claude-haiku-4-5-20251001":{ input: 0.000001,    output: 0.000005   },
     "claude-3-opus-20240229":   { input: 0.000015,    output: 0.000075   },
     "claude-3-sonnet-20240229": { input: 0.000003,    output: 0.000015   },
     "claude-3-haiku-20240307":  { input: 0.00000025,  output: 0.00000125 },
@@ -188,3 +191,83 @@ export function priceGemini(model, usage = {}) {
       : null,
   };
 }
+
+// ── Anthropic ────────────────────────────────────────────────────────────────
+
+/**
+ * Prompt caching da Anthropic: gravação no cache custa um múltiplo do preço de
+ * ENTRADA (1,25x com validade de 5 min, 2x com 1 h) e leitura, 0,1x. Os tokens
+ * de cache NÃO aparecem em `usage.input_tokens` — vêm em campos próprios.
+ * Calcular só sobre `input_tokens` subconta o custo assim que o cache é ligado.
+ */
+export const ANTHROPIC_CACHE_MULTIPLIERS = Object.freeze({ write5m: 1.25, write1h: 2, read: 0.1 });
+
+// Snapshot datado da Anthropic: `claude-haiku-4-5-20251001`.
+const ANTHROPIC_VERSION_SUFFIX = /-\d{8}$/;
+
+const nonNeg = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : 0);
+
+/**
+ * Custo de uma chamada da Messages API da Anthropic a partir do `usage`.
+ *
+ * Modelo fora da tabela sai com `costUSD: null` + `unpriced: true` — nunca o
+ * preço de outro modelo (antes caía no do Sonnet 4.6, o que superfaturava um
+ * Haiku em 3x e subfaturava um Opus). Snapshot com sufixo de data não listado
+ * usa o preço do modelo-base, declarado em `approxPricing`.
+ *
+ * `inputTokens` é o total de entrada processada (sem cache + gravado + lido),
+ * mesma semântica do Gemini (`promptTokenCount` já inclui o cache). A parte de
+ * cache vai também separada em `cacheWriteTokens`/`cacheReadTokens`.
+ */
+export function priceAnthropic(model, usage = {}) {
+  const u = usage || {};
+  const plain  = nonNeg(u.input_tokens);
+  const output = nonNeg(u.output_tokens);
+  const read   = nonNeg(u.cache_read_input_tokens);
+  const br = u.cache_creation;
+  let write5m, write1h;
+  if (br && typeof br === "object" && ("ephemeral_5m_input_tokens" in br || "ephemeral_1h_input_tokens" in br)) {
+    write5m = nonNeg(br.ephemeral_5m_input_tokens);
+    write1h = nonNeg(br.ephemeral_1h_input_tokens);
+  } else {
+    write5m = nonNeg(u.cache_creation_input_tokens);
+    write1h = 0;
+  }
+  const inputTokens = plain + write5m + write1h + read;
+  const base = {
+    inputTokens,
+    outputTokens:     output,
+    totalTokens:      inputTokens + output,
+    cacheWriteTokens: write5m + write1h,
+    cacheReadTokens:  read,
+  };
+
+  const table = PRICING.anthropic;
+  const name = typeof model === "string" ? model : "";
+  let id = null, approx = false;
+  if (name && Object.hasOwn(table, name)) {
+    id = name;
+  } else {
+    const b = name.replace(ANTHROPIC_VERSION_SUFFIX, "");
+    if (b !== name && Object.hasOwn(table, b)) { id = b; approx = true; }
+  }
+  if (!id) {
+    return {
+      ...base, costUSD: null, pricedAs: null, approxPricing: false, unpriced: true,
+      reason: `Modelo "${name.slice(0, 60) || "desconhecido"}" não está na tabela de preço da Anthropic — tokens registrados, custo não estimado.`,
+    };
+  }
+  const r = table[id];
+  const m = ANTHROPIC_CACHE_MULTIPLIERS;
+  const costUSD = plain * r.input
+    + (write5m * m.write5m + write1h * m.write1h + read * m.read) * r.input
+    + output * r.output;
+  return {
+    ...base,
+    costUSD:       parseFloat(costUSD.toFixed(8)),
+    pricedAs:      id,
+    approxPricing: approx,
+    unpriced:      false,
+    reason:        approx ? `Preço do modelo base "${id}" aplicado a "${name.slice(0, 60)}" — snapshot não listado na tabela.` : null,
+  };
+}

package/src/test-executions.js

@@ -0,0 +1,190 @@
+/**
+ * Contador de execuções (0.8.0). Execute: node src/test-executions.js
+ * Sem rede: fetch é substituído por um falso que registra o que seria enviado.
+ */
+import assert from "node:assert";
+import { readFileSync } from "node:fs";
+import { ExecutionCounter, resolveVersion } from "./executions.js";
+import { CloudBrokerCloud } from "./cloud-wrapper.js";
+import { cbStore } from "./context.js";
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log("✅", msg); };
+
+const realFetch = globalThis.fetch;
+const sent = [];
+let respond = () => ({ ok: true, status: 200 });
+globalThis.fetch = async (url, opts) => {
+  sent.push({ url, headers: opts.headers, body: JSON.parse(opts.body) });
+  const r = respond();
+  if (r instanceof Error) throw r;
+  return r;
+};
+
+const T0 = Date.parse("2026-10-12T15:42:10.000Z");
+let clock = T0;
+const mk = (o = {}) => new ExecutionCounter({ apiKey: "cb-test", flushIntervalMs: 0, now: () => clock, ...o });
+
+// ─── versão ──────────────────────────────────────────────────────────────────
+delete process.env.CLOUDBROKER_VERSION;
+ok(resolveVersion() === null, "sem versão e sem env → null (nunca inventa versão)");
+process.env.CLOUDBROKER_VERSION = " abc1234 ";
+ok(resolveVersion() === "abc1234", "versão vem de CLOUDBROKER_VERSION, sem espaços");
+ok(resolveVersion("v2") === "v2", "versão explícita vence o env");
+ok(resolveVersion("x".repeat(100)).length === 64, "versão com teto de 64");
+
+// ─── agregação ───────────────────────────────────────────────────────────────
+{
+  const c = mk();
+  c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Loja" });
+  c.count({ label: "checkout", product: "Outro" });
+  ok(c.pendingKeys === 2, "mesmo trecho+app+hora vira 1 combinação; app diferente, outra");
+  c.count({ label: "" }); c.count({}); c.count(null); c.count({ label: 42 });
+  ok(c.pendingKeys === 2, "sem rótulo não conta e não lança");
+  await c.flush();
+  const body = sent.at(-1).body.executions;
+  const loja = body.find((e) => e.product === "Loja");
+  ok(loja.count === 3 && loja.hour === "2026-10-12T15:00:00.000Z" && loja.version === "abc1234", "lote enviado: contagem somada, início da hora em UTC, versão anexada");
+  ok(sent.at(-1).url.endsWith("/api/cloud/executions") && sent.at(-1).headers["x-cloudbroker-key"] === "cb-test", "endpoint e cabeçalho da key");
+  ok(c.pendingKeys === 0, "enviado com sucesso → fila vazia");
+
+  clock = T0 + 3_600_000;
+  c.count({ label: "checkout", product: "Loja" });
+  clock = T0;
+  c.count({ label: "checkout", product: "Loja" });
+  ok(c.pendingKeys === 2, "horas diferentes são combinações diferentes");
+}
+
+// ─── teto de memória ─────────────────────────────────────────────────────────
+{
+  const c = mk({ maxKeys: 3 });
+  for (let i = 0; i < 5; i++) c.count({ label: `/api/apps/${i}` });
+  c.count({ label: "/api/apps/0" });
+  ok(c.pendingKeys === 3 && c.dropped === 2, "acima do teto de combinações descarta e conta em dropped (rótulo com id não cresce sem limite)");
+  const big = mk({ maxKeys: 5000 });
+  for (let i = 0; i < 250; i++) big.count({ label: `t${i}` });
+  ok(big.pendingKeys === 200 && big.dropped === 50, "maxKeys efetivo nunca passa de 200");
+}
+
+// ─── falha de envio ──────────────────────────────────────────────────────────
+{
+  const c = mk();
+  c.count({ label: "a" }); c.count({ label: "a" });
+  respond = () => new Error("ECONNRESET");
+  await c.flush();
+  ok(c.pendingKeys === 1, "erro de rede → a contagem volta para a fila");
+  c.count({ label: "a" });
+  respond = () => ({ ok: false, status: 503 });
+  await c.flush();
+  respond = () => ({ ok: true, status: 200 });
+  await c.flush();
+  ok(sent.at(-1).body.executions[0].count === 3, "503 também volta para a fila, e a contagem não se perde nem duplica");
+
+  c.count({ label: "b" });
+  respond = () => ({ ok: false, status: 400 });
+  await c.flush();
+  ok(c.pendingKeys === 0, "4xx é recusa definitiva → descartado, sem reenviar para sempre");
+  respond = () => ({ ok: false, status: 429 });
+  c.count({ label: "b" });
+  await c.flush();
+  ok(c.pendingKeys === 1, "429 volta para a fila");
+  respond = () => ({ ok: true, status: 200 });
+
+  const velho = mk();
+  velho.count({ label: "v" });
+  respond = () => new Error("offline");
+  clock = T0 + 8 * 24 * 3_600_000; // o flush falha 8 dias depois
+  await velho.flush();
+  clock = T0;
+  respond = () => ({ ok: true, status: 200 });
+  ok(velho.pendingKeys === 0 && velho.dropped === 1, "contagem com mais de 7 dias não volta para a fila (o backend recusaria)");
+}
+
+// ─── nunca lança, e não segura o processo ────────────────────────────────────
+{
+  // Timer padrão (60s) SEM stop(): um processo filho precisa terminar sozinho.
+  // Sem o .unref(), o timer seguraria o event loop e o filho não sairia.
+  const { spawnSync } = await import("node:child_process");
+  const filho = spawnSync(process.execPath, ["--input-type=module", "-e",
+    `import { ExecutionCounter } from ${JSON.stringify(new URL("./executions.js", import.meta.url).href)};
+     const c = new ExecutionCounter({ apiKey: "cb-test" }); c.count({ label: "x" });`], { timeout: 10_000 });
+  ok(filho.status === 0 && !filho.error, "o timer do contador não segura o processo (Lambda, cron, CLI terminam sozinhos)");
+
+  const c = mk();
+  respond = () => { throw new TypeError("fetch quebrado"); };
+  c.count({ label: "x" });
+  await c.flush();
+  respond = () => ({ ok: true, status: 200 });
+  ok(true, "fetch que lança não escapa do flush");
+  c.stop();
+  assert.throws(() => new ExecutionCounter({}), /apiKey/);
+  ok(true, "sem apiKey lança na construção (erro de configuração, não de execução)");
+}
+
+// ─── expressMiddleware ───────────────────────────────────────────────────────
+{
+  const c = mk();
+  const mw = CloudBrokerCloud.expressMiddleware({ label: (req) => `mod:${req.path}`, product: "Loja", executions: c });
+  let vistoNoContexto;
+  await new Promise((r) => mw({ method: "GET", path: "/x" }, {}, () => { vistoNoContexto = cbStore.getStore(); r(); }));
+  await new Promise((r) => mw({ method: "GET", path: "/x" }, {}, r));
+  await c.flush();
+  const ex = sent.at(-1).body.executions;
+  ok(ex.length === 1 && ex[0].label === "mod:/x" && ex[0].product === "Loja" && ex[0].count === 2, "uma execução por requisição, com o mesmo trecho/app do contexto");
+  ok(vistoNoContexto?.label === "mod:/x", "o contexto continua chegando ao handler");
+
+  const quebrado = { count() { throw new Error("boom"); } };
+  const mw2 = CloudBrokerCloud.expressMiddleware({ label: "a", executions: quebrado });
+  let passou = false;
+  mw2({ method: "GET", path: "/" }, {}, () => { passou = true; });
+  ok(passou, "contador que lança não derruba a requisição (next é chamado)");
+  const mw3 = CloudBrokerCloud.expressMiddleware({ label: "a" });
+  let chamou = false;
+  mw3({ method: "GET", path: "/" }, {}, () => { chamou = true; });
+  ok(chamou, "sem `executions`, o middleware se comporta como antes");
+}
+
+// ─── trackExecution ──────────────────────────────────────────────────────────
+{
+  const c = mk();
+  const r1 = CloudBrokerCloud.trackExecution("job:fechamento", () => cbStore.getStore().label, { executions: c, product: "Financeiro" });
+  ok(r1 === "job:fechamento", "fn roda dentro do contexto do trecho e o retorno é devolvido");
+  const r2 = await CloudBrokerCloud.trackExecution("job:fechamento", async () => 7, { executions: c, product: "Financeiro" });
+  ok(r2 === 7, "fn assíncrona: devolve a Promise");
+  let erro;
+  try { await CloudBrokerCloud.trackExecution("job:fechamento", async () => { throw new Error("falha do job"); }, { executions: c, product: "Financeiro" }); } catch (e) { erro = e; }
+  ok(erro?.message === "falha do job", "erro de fn propaga intacto (a instrumentação não o engole)");
+  await c.flush();
+  ok(sent.at(-1).body.executions[0].count === 3, "cada chamada conta uma execução (inclusive a que falhou)");
+  ok(CloudBrokerCloud.trackExecution("x", () => 1, { executions: { count() { throw new Error("x"); } } }) === 1, "contador que lança não derruba a execução");
+  ok(CloudBrokerCloud.trackExecution("x", () => 2) === 2, "sem contador funciona só como contexto");
+}
+
+// ─── versão nos eventos de chamada ───────────────────────────────────────────
+{
+  process.env.CLOUDBROKER_VERSION = "abc1234";
+  class S3Client { constructor() { this.config = { region: async () => "us-east-2" }; } async send() { return {}; } }
+  class GetObjectCommand { constructor(input) { this.input = input; } }
+  const s3 = CloudBrokerCloud.wrapAWS(new S3Client(), { apiKey: "cb-test" });
+  await s3.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
+  await new Promise((r) => setTimeout(r, 30));
+  const ev = sent.filter((s) => s.url.endsWith("/api/cloud/events")).at(-1)?.body.events[0];
+  ok(ev?.version === "abc1234", `evento de chamada leva a versão do código (veio ${ev?.version})`);
+  const s3b = CloudBrokerCloud.wrapAWS(new S3Client(), { apiKey: "cb-test", version: "v9" });
+  await s3b.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));
+  await new Promise((r) => setTimeout(r, 30));
+  ok(sent.filter((s) => s.url.endsWith("/api/cloud/events")).at(-1)?.body.events[0].version === "v9", "versão explícita do wrapAWS vence o env");
+}
+
+// ─── versão do pacote ────────────────────────────────────────────────────────
+{
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  const client = readFileSync(new URL("./client.js", import.meta.url), "utf8");
+  const declaradas = [...client.matchAll(/sdkVersion:\s*"([^"]+)"/g)].map((m) => m[1]);
+  ok(declaradas.length > 0 && declaradas.every((v) => v === pkg.version), `sdkVersion dos eventos (${declaradas.join(", ")}) = versão do package.json (${pkg.version})`);
+}
+
+globalThis.fetch = realFetch;
+console.log(`\n🎉 ${pass} asserções passaram.`);

package/src/test.js

@@ -489,5 +489,75 @@ console.warn = origWarn;
 assert.strictEqual(await untouched.foo(), 42);
 assert.ok(warns.some(w => w.includes("não reconhecido")), "deve avisar mesmo sem debug:true");
 console.log("✅ wrapAzure: client não reconhecido passa intocado, com aviso incondicional");
+// 10) Anthropic: preço conferido (2026-10-12), tokens de cache e modelo
+// desconhecido sem preço fabricado.
+{
+  const { priceAnthropic, PRICING: P } = await import("./pricing.js");
+  assert.strictEqual(P.anthropic["claude-haiku-4-5-20251001"].input, 0.000001, "Haiku 4.5 entrada = US$ 1/M (não o preço do Haiku 3)");
+  assert.strictEqual(P.anthropic["claude-haiku-4-5-20251001"].output, 0.000005, "Haiku 4.5 saída = US$ 5/M");
+  assert.strictEqual(P.anthropic["claude-opus-4-6"].input, 0.000005, "Opus 4.6 entrada = US$ 5/M");
+  assert.strictEqual(P.anthropic["claude-opus-4-6"].output, 0.000025, "Opus 4.6 saída = US$ 25/M");
+
+  const h = priceAnthropic("claude-haiku-4-5-20251001", { input_tokens: 1_000_000, output_tokens: 1_000_000 });
+  assert.ok(Math.abs(h.costUSD - 6) < 1e-9, `1M+1M no Haiku 4.5 = US$ 6, veio ${h.costUSD}`);
+
+  const c = priceAnthropic("claude-haiku-4-5-20251001", {
+    input_tokens: 1000, output_tokens: 100, cache_creation_input_tokens: 10000, cache_read_input_tokens: 20000,
+  });
+  const esperado = 1000 * 1e-6 + 100 * 5e-6 + 10000 * 1e-6 * 1.25 + 20000 * 1e-6 * 0.1;
+  assert.ok(Math.abs(c.costUSD - esperado) < 1e-9, `gravação 1,25x e leitura 0,1x, esperado ${esperado}, veio ${c.costUSD}`);
+  assert.strictEqual(c.inputTokens, 31000, "inputTokens = sem cache + gravado + lido");
+  assert.strictEqual(c.cacheWriteTokens, 10000);
+  assert.strictEqual(c.cacheReadTokens, 20000);
+
+  const h1 = priceAnthropic("claude-haiku-4-5-20251001", {
+    cache_creation_input_tokens: 1000, cache_creation: { ephemeral_5m_input_tokens: 0, ephemeral_1h_input_tokens: 1000 },
+  });
+  assert.ok(Math.abs(h1.costUSD - 1000 * 1e-6 * 2) < 1e-12, "gravação com validade de 1 h custa 2x");
+
+  const d = priceAnthropic("claude-modelo-inventado", { input_tokens: 10, output_tokens: 10 });
+  assert.strictEqual(d.costUSD, null, "modelo desconhecido não recebe o preço de outro modelo");
+  assert.strictEqual(d.unpriced, true);
+  assert.strictEqual(d.totalTokens, 20, "tokens registrados mesmo sem preço");
+
+  const a = priceAnthropic("claude-sonnet-4-6-20991231", { input_tokens: 1000 });
+  assert.ok(a.approxPricing === true && a.pricedAs === "claude-sonnet-4-6", "snapshot datado não listado usa o modelo-base, declarado");
+
+  for (const nome of ["constructor", "__proto__", "toString", "hasOwnProperty"]) {
+    const v = priceAnthropic(nome, { input_tokens: 10 });
+    assert.strictEqual(v.costUSD, null, `nome venenoso "${nome}" não vira tabela de preço`);
+  }
+  const lixo = priceAnthropic("claude-haiku-4-5-20251001", { input_tokens: -5, output_tokens: "x", cache_read_input_tokens: NaN });
+  assert.strictEqual(lixo.costUSD, 0, "valor negativo ou não numérico conta como 0, nunca NaN");
+  assert.strictEqual(priceAnthropic(undefined, undefined).costUSD, null, "sem modelo e sem usage não lança");
+  console.log("✅ priceAnthropic: preço conferido, cache 1,25x/2x/0,1x, desconhecido = null");
+
+  // wrap: o evento enviado leva o custo com cache e o sinal de sem preço
+  const capt = [];
+  globalThis.fetch = async (url, opts) => {
+    if (String(url).includes("/api/ai/events")) capt.push(...JSON.parse(opts.body).events);
+    return { ok: true, status: 200, json: async () => ({}) };
+  };
+  const mockAnthropic = {
+    messages: {
+      create: async (params) => ({
+        model: params.model, content: [],
+        usage: { input_tokens: 1000, output_tokens: 100, cache_creation_input_tokens: 10000, cache_read_input_tokens: 20000 },
+      }),
+    },
+  };
+  const wa = CloudBrokerAI.wrap(mockAnthropic, { apiKey: "cb-test-key", product: "FinOps Advisor" });
+  await wa.messages.create({ model: "claude-haiku-4-5-20251001", max_tokens: 10, messages: [] }, { cbLabel: "finops-advisor:agent" });
+  await wa.messages.create({ model: "claude-modelo-inventado", max_tokens: 10, messages: [] });
+  await new Promise((r) => setTimeout(r, 50));
+  assert.strictEqual(capt.length, 2, `esperado 2 eventos de IA, veio ${capt.length}`);
+  assert.ok(Math.abs(capt[0].costUSD - esperado) < 1e-9, `evento leva o custo com cache, veio ${capt[0].costUSD}`);
+  assert.strictEqual(capt[0].cacheReadTokens, 20000);
+  assert.strictEqual(capt[0].label, "finops-advisor:agent");
+  assert.strictEqual(capt[1].costUSD, null, "evento de modelo desconhecido sai com costUSD null");
+  assert.strictEqual(capt[1].unpriced, true);
+  console.log("✅ CloudBrokerAI.wrap (Anthropic): custo com cache no evento, desconhecido = null");
+}
+
 globalThis.fetch = realFetch;
 console.log("\n🎉 Todos os testes passaram.");

package/src/wrapper.js

@@ -4,9 +4,37 @@
  */
 
 import { CloudBrokerClient } from "./client.js";
-import { PRICING, priceGemini } from "./pricing.js";
+import { PRICING, priceGemini, priceAnthropic } from "./pricing.js";
 import { cbStore } from "./context.js";
 
+/**
+ * Evento de uma chamada da Anthropic. O preço vem de `priceAnthropic`: inclui
+ * os tokens de cache e devolve `costUSD: null` + `unpriced` para modelo fora
+ * da tabela (nunca o preço de outro modelo).
+ */
+function anthropicEvent(model, usage, { product, team, label, start, latencyMs, streaming }) {
+  const p = priceAnthropic(model, usage || {});
+  const ev = {
+    provider:         "anthropic",
+    model,
+    product:          product || null,
+    team:             team    || null,
+    label,
+    inputTokens:      p.inputTokens,
+    outputTokens:     p.outputTokens,
+    totalTokens:      p.totalTokens,
+    costUSD:          p.costUSD,
+    cacheWriteTokens: p.cacheWriteTokens,
+    cacheReadTokens:  p.cacheReadTokens,
+    unpriced:         p.unpriced,
+    pricingNote:      p.reason,
+    latencyMs:        latencyMs ?? (Date.now() - start),
+    endpoint:         "messages",
+  };
+  if (streaming) ev.streaming = true;
+  return ev;
+}
+
 export class CloudBrokerAI {
   /**
    * Envolve um cliente OpenAI ou Anthropic
@@ -189,35 +217,20 @@ export class CloudBrokerAI {
         const stream = await originalCreate(params, fwdOptions);
 
         let model = params.model || "unknown";
-        let inputTokens = 0, outputTokens = 0;
+        // usage de entrada (incl. tokens de cache) vem no message_start;
+        // message_delta traz o total acumulado de output_tokens.
+        let usage = {};
         const onChunk = (event) => {
           if (event?.type === "message_start" && event.message) {
-            model        = event.message.model || model;
-            inputTokens  = event.message.usage?.input_tokens  || inputTokens;
-            outputTokens = event.message.usage?.output_tokens || outputTokens;
+            model = event.message.model || model;
+            if (event.message.usage) usage = { ...event.message.usage };
           } else if (event?.type === "message_delta" && event.usage) {
-            // message_delta traz o total acumulado de output_tokens
-            outputTokens = event.usage.output_tokens || outputTokens;
+            if (event.usage.output_tokens != null) usage.output_tokens = event.usage.output_tokens;
           }
         };
         const onDone = () => {
           try {
-            const pricing = PRICING.anthropic[model] || PRICING.anthropic["claude-sonnet-4-6"];
-            const costUSD = (inputTokens * pricing.input) + (outputTokens * pricing.output);
-            cb.track({
-              provider:    "anthropic",
-              model,
-              product:     product || null,
-              team:        team    || null,
-              label:       cbLabel,
-              inputTokens,
-              outputTokens,
-              totalTokens: inputTokens + outputTokens,
-              costUSD:     parseFloat(costUSD.toFixed(6)),
-              latencyMs:   Date.now() - start,
-              endpoint:    "messages",
-              streaming:   true,
-            });
+            cb.track(anthropicEvent(model, usage, { product, team, label: cbLabel, start, streaming: true }));
           } catch (err) {
             if (debug) console.warn("[CloudBroker] track error:", err.message);
           }
@@ -231,25 +244,8 @@ export class CloudBrokerAI {
       const ms  = Date.now() - start;
 
       try {
-        const model        = res.model || params.model || "unknown";
-        const inputTokens  = res.usage?.input_tokens  || 0;
-        const outputTokens = res.usage?.output_tokens || 0;
-        const pricing      = PRICING.anthropic[model] || PRICING.anthropic["claude-sonnet-4-6"];
-        const costUSD      = (inputTokens * pricing.input) + (outputTokens * pricing.output);
-
-        cb.track({
-          provider:      "anthropic",
-          model,
-          product:       product || null,
-          team:          team    || null,
-          label:         cbLabel,
-          inputTokens,
-          outputTokens,
-          totalTokens:   inputTokens + outputTokens,
-          costUSD:       parseFloat(costUSD.toFixed(6)),
-          latencyMs:     ms,
-          endpoint:      "messages",
-        });
+        const model = res.model || params.model || "unknown";
+        cb.track(anthropicEvent(model, res.usage, { product, team, label: cbLabel, start, latencyMs: ms }));
       } catch (err) {
         if (debug) console.warn("[CloudBroker] track error:", err.message);
       }