cloudbroker-sdk 0.6.0 → 0.8.0

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

@@ -46,6 +46,62 @@ const res = await anthropic.messages.create({
 });
 ```
 
+## Uso com Gemini
+
+```js
+import { GoogleGenAI } from "@google/genai";
+import { CloudBrokerAI } from "cloudbroker-sdk";
+
+const gemini = CloudBrokerAI.wrap(new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }), {
+  apiKey:  "cb-key-xxxx",
+  product: "checkout",
+  team:    "mobile",
+});
+
+const res = await gemini.models.generateContent({
+  model:    "gemini-2.5-flash",
+  contents: "Olá!",
+});
+```
+
+O `cbLabel` pode ir no próprio params (a API do Gemini é de argumento único) ou
+no segundo argumento, como nos outros wrappers. Nos dois casos ele é removido
+antes de a chamada seguir pro Google:
+
+```js
+await gemini.models.generateContent({
+  model: "gemini-2.5-flash", contents: "…", cbLabel: "checkout:resumo-pedido",
+});
+```
+
+### Por que o custo do Gemini não é `input × preço + output × preço`
+
+A conta do Gemini tem três particularidades. Ignorar qualquer uma delas erra o
+valor de forma relevante, então o SDK trata as três:
+
+| Particularidade | O que acontece se ignorar |
+|---|---|
+| `promptTokenCount` **já inclui** os tokens servidos de cache, que custam ~10x menos | superfatura a parcela cacheada (1,65x a mais num prompt 80% cacheado) |
+| `thoughtsTokenCount` é separado de `candidatesTokenCount` e é cobrado como output | subfatura — 33x a menos num caso com 2000 thinking tokens |
+| 2.5 Pro dobra de preço acima de 200k tokens de prompt; áudio na entrada custa mais que texto | subfatura prompts longos e entrada de áudio |
+
+### Limitações declaradas
+
+- **O custo é estimado por tabela de preço local**, não lido de uma fatura. O
+  Gemini não expõe API de uso ou custo por chave — só o dashboard do AI Studio
+  e o console do Cloud Billing. Os preços são os do paid tier publicados em
+  `ai.google.dev/gemini-api/docs/pricing`, conferidos em 2026-08-02, e **não
+  foram calibrados contra fatura real**.
+- **Free tier sai com custo > 0.** A tabela é a do paid tier; quem está no free
+  tier vê o valor que *pagaria*, não o que paga.
+- **Modelo fora da tabela não recebe preço de outro modelo.** O evento vai com
+  `costUSD: null` e `unpriced: true`, preservando os tokens. Variante com sufixo
+  (`-preview-…`) é precificada pelo modelo base e marcada `approxPricing`.
+- **Armazenamento de contexto em cache não é cobrado aqui.** O Google cobra por
+  hora de cache ativo (US$ 1,00/h na maioria dos modelos); isso não aparece no
+  `usageMetadata` de uma chamada e não é modelado.
+- **Batch API não é modelada** — o Google cobra metade nesse modo.
+
 ## Streaming
 
 Chamadas com `stream: true` também são rastreadas — o SDK observa os chunks
@@ -253,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.6.0",
+  "version": "0.8.0",
   "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"
+    "test": "node src/test.js && node src/test-executions.js && node src/test-azure-real.js && node src/test-gemini-real.js"
   },
   "keywords": [
     "cloudbroker",
@@ -20,6 +24,7 @@
   "license": "MIT",
   "devDependencies": {
     "@azure/cosmos": "^4.10.0",
-    "@azure/storage-blob": "^12.33.0"
+    "@azure/storage-blob": "^12.33.0",
+    "@google/genai": "^2.15.0"
   }
 }

package/src/client.js

@@ -48,7 +48,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.6.0",
+        sdkVersion: "0.8.0",
         sentAt: new Date().toISOString(),
       };
       if (this.#cloudQueue.length < MAX_QUEUE_SIZE) {
@@ -104,7 +104,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.6.0",
+        sdkVersion: "0.8.0",
         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

@@ -24,9 +24,167 @@ export const PRICING = {
     "claude-3-sonnet-20240229": { input: 0.000003,    output: 0.000015   },
     "claude-3-haiku-20240307":  { input: 0.00000025,  output: 0.00000125 },
   },
+  /**
+   * Gemini — preços do paid tier em ai.google.dev/gemini-api/docs/pricing,
+   * conferidos em 2026-08-02. A página publica por 1M de tokens; aqui, como no
+   * resto da tabela, o valor é por token.
+   *
+   * A conta do Gemini tem três particularidades que um par `{input, output}`
+   * plano não expressa — ignorar qualquer uma delas erra o custo de verdade:
+   *
+   *  - `cached`     — prompt servido de cache custa ~10x menos. Atenção:
+   *                   `promptTokenCount` JÁ INCLUI os tokens cacheados, então o
+   *                   input a preço cheio é `prompt - cached`. Cobrar o prompt
+   *                   inteiro a preço cheio superfatura em 10x essa parcela.
+   *  - `audioInput` — áudio na entrada custa mais que texto/imagem/vídeo nos
+   *                   Flash e Flash-Lite. A separação sai de
+   *                   `promptTokensDetails[].modality === "AUDIO"`.
+   *  - `tierOver`   — o 2.5 Pro dobra acima de 200k tokens de prompt.
+   *
+   * Os modelos 1.5/2.0 que existiam aqui foram removidos: a página oficial não
+   * os lista mais, e manter preço não verificável é fabricar custo. Eles caem
+   * agora no caminho de modelo desconhecido (`costUSD: null`), que é honesto.
+   *
+   * Thinking tokens não aparecem nesta tabela porque não têm preço próprio —
+   * a página diz "Output price (including thinking tokens)", ou seja, são
+   * cobrados como output. Quem soma é `priceGemini()`.
+   */
   gemini: {
-    "gemini-1.5-pro":           { input: 0.0000035,   output: 0.0000105  },
-    "gemini-1.5-flash":         { input: 0.00000035,  output: 0.00000105 },
-    "gemini-2.0-flash":         { input: 0.0000001,   output: 0.0000004  },
+    "gemini-3.6-flash":      { input: 0.0000015,  output: 0.0000075, cached: 0.00000015 },
+    "gemini-3.5-flash":      { input: 0.0000015,  output: 0.000009,  cached: 0.00000015 },
+    "gemini-3.5-flash-lite": { input: 0.0000003,  output: 0.0000025, cached: 0.00000003 },
+    "gemini-3.1-flash-lite": {
+      input: 0.00000025, output: 0.0000015, cached: 0.000000025,
+      audioInput: 0.0000005, audioCached: 0.00000005,
+    },
+    "gemini-2.5-pro": {
+      input: 0.00000125, output: 0.00001, cached: 0.000000125,
+      tierOver: {
+        promptTokens: 200000,
+        input: 0.0000025, output: 0.000015, cached: 0.00000025,
+      },
+    },
+    "gemini-2.5-flash": {
+      input: 0.0000003, output: 0.0000025, cached: 0.00000003,
+      audioInput: 0.000001, audioCached: 0.0000001,
+    },
+    "gemini-2.5-flash-lite": {
+      input: 0.0000001, output: 0.0000004, cached: 0.00000001,
+      audioInput: 0.0000003, audioCached: 0.00000003,
+    },
   },
 };
+
+/**
+ * Resolve a entrada de preço de um modelo Gemini.
+ *
+ * A API devolve `modelVersion` que muitas vezes carrega sufixo (`-preview-…`,
+ * data). Exigir igualdade exata deixaria quase toda resposta real sem preço;
+ * casar por prefixo sem avisar seria afirmar que preview custa o mesmo que GA,
+ * o que não é garantido. Então: exato é exato, prefixo é marcado `approx`, e o
+ * que não casa não recebe preço de outro modelo.
+ *
+ * @returns {{ id: string, rates: object, approx: boolean } | null}
+ */
+function resolveGeminiModel(model) {
+  if (!model) return null;
+  const table = PRICING.gemini;
+  if (table[model]) return { id: model, rates: table[model], approx: false };
+
+  // Prefixo mais longo primeiro: "gemini-3.5-flash-lite" tem que ganhar de
+  // "gemini-3.5-flash" para "gemini-3.5-flash-lite-preview-01".
+  const match = Object.keys(table)
+    .filter(id => model.startsWith(id))
+    .sort((a, b) => b.length - a.length)[0];
+
+  return match ? { id: match, rates: table[match], approx: true } : null;
+}
+
+/**
+ * Calcula o custo de uma chamada Gemini a partir do `usageMetadata` da resposta.
+ *
+ * Nomes de campo conferidos nos tipos do @google/genai@2.15.0 — a doc pública
+ * mostra um formato snake_case (`total_input_tokens`) que é de outra superfície
+ * da API; o `generateContent` devolve camelCase.
+ *
+ * @param {string} model — `modelVersion` da resposta, ou o pedido na chamada
+ * @param {object} usage — `response.usageMetadata`
+ * @returns {{
+ *   costUSD: number|null, inputTokens: number, outputTokens: number,
+ *   totalTokens: number, cachedTokens: number, thoughtsTokens: number,
+ *   audioInputTokens: number, pricedAs: string|null, approxPricing: boolean,
+ *   unpriced: boolean, reason: string|null
+ * }}
+ */
+export function priceGemini(model, usage = {}) {
+  const prompt   = usage.promptTokenCount        || 0;
+  const cached   = usage.cachedContentTokenCount || 0;
+  const output   = usage.candidatesTokenCount    || 0;
+  const thoughts = usage.thoughtsTokenCount      || 0;
+  const toolUse  = usage.toolUsePromptTokenCount || 0;
+
+  // `prompt` já inclui `cached` — o restante é que sai a preço cheio.
+  // Nunca deixar negativo: se a API mudar a semântica, subfaturar em silêncio
+  // é pior do que somar 0.
+  const fullPriceInput = Math.max(0, prompt - cached);
+
+  // Áudio na entrada tem preço próprio em parte dos modelos. O detalhamento
+  // por modalidade se refere ao prompt inteiro (cacheado incluso), então o
+  // recorte de áudio a preço cheio é proporcional ao que não veio de cache.
+  const audioDetail = (usage.promptTokensDetails || [])
+    .find(d => d?.modality === "AUDIO")?.tokenCount || 0;
+  const audioFullPrice = prompt > 0
+    ? Math.round(audioDetail * (fullPriceInput / prompt))
+    : 0;
+  const audioCached = Math.max(0, audioDetail - audioFullPrice);
+
+  const base = {
+    inputTokens:      prompt + toolUse,
+    outputTokens:     output + thoughts,
+    totalTokens:      usage.totalTokenCount || (prompt + output + thoughts + toolUse),
+    cachedTokens:     cached,
+    thoughtsTokens:   thoughts,
+    audioInputTokens: audioDetail,
+  };
+
+  const resolved = resolveGeminiModel(model);
+  if (!resolved) {
+    return {
+      ...base,
+      costUSD:       null,
+      pricedAs:      null,
+      approxPricing: false,
+      unpriced:      true,
+      reason:        `Modelo "${model || "desconhecido"}" não está na tabela de preço do Gemini — tokens registrados, custo não estimado.`,
+    };
+  }
+
+  // O 2.5 Pro troca de faixa pelo tamanho do prompt.
+  let rates = resolved.rates;
+  if (rates.tierOver && prompt > rates.tierOver.promptTokens) {
+    rates = { ...rates, ...rates.tierOver };
+  }
+
+  const textFullPrice = Math.max(0, fullPriceInput - audioFullPrice);
+  const textCached    = Math.max(0, cached - audioCached);
+
+  const costUSD =
+      textFullPrice  * rates.input
+    + audioFullPrice * (rates.audioInput  ?? rates.input)
+    + textCached     * (rates.cached      ?? rates.input)
+    + audioCached    * (rates.audioCached ?? rates.cached ?? rates.input)
+    + toolUse        * rates.input
+    // Thinking tokens são cobrados como output.
+    + (output + thoughts) * rates.output;
+
+  return {
+    ...base,
+    costUSD:       parseFloat(costUSD.toFixed(8)),
+    pricedAs:      resolved.id,
+    approxPricing: resolved.approx,
+    unpriced:      false,
+    reason:        resolved.approx
+      ? `Preço do modelo base "${resolved.id}" aplicado a "${model}" — variante não listada na tabela oficial.`
+      : 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-gemini-real.js

@@ -0,0 +1,270 @@
+/**
+ * Teste do wrapGemini contra o cliente REAL do @google/genai — não contra uma
+ * fake escrita à mão.
+ *
+ * Por que existe: a mesma razão do test-azure-real.js. Uma fake desenhada pra
+ * casar com a implementação não reprova suposição errada sobre o SDK de
+ * verdade. E aqui havia uma suposição especialmente perigosa: a doc pública do
+ * Gemini mostra o usage em snake_case (`total_input_tokens`), que pertence a
+ * outra superfície da API — o `generateContent` devolve camelCase
+ * (`promptTokenCount`). Ter errado isso daria token zero em silêncio, sem
+ * nenhum erro. Este arquivo trava os nomes contra os tipos do pacote instalado.
+ *
+ * Não faz chamada de rede: a chave é sintética e o método original é
+ * substituído por um stub antes do wrap ser exercitado.
+ *
+ * Execute: node src/test-gemini-real.js
+ */
+import assert from "node:assert";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { GoogleGenAI } from "@google/genai";
+import { CloudBrokerAI } from "./wrapper.js";
+import { priceGemini, PRICING } from "./pricing.js";
+
+const require = createRequire(import.meta.url);
+
+// O pacote não expõe "./package.json" em `exports`, então o caminho dos tipos
+// é derivado do entry point resolvido (.../dist/node/index.cjs → .../dist).
+function typingsPath() {
+  const entry = require.resolve("@google/genai");
+  return entry.slice(0, entry.indexOf("/dist/") + "/dist/".length) + "genai.d.ts";
+}
+
+let ok = 0, fail = 0;
+const t = (name, fn) => {
+  try { fn(); console.log(`✅ ${name}`); ok++; }
+  catch (e) { console.error(`❌ ${name}\n   ${e.message}`); fail++; }
+};
+const ta = async (name, fn) => {
+  try { await fn(); console.log(`✅ ${name}`); ok++; }
+  catch (e) { console.error(`❌ ${name}\n   ${e.message}`); fail++; }
+};
+
+console.log("🧪 wrapGemini contra o SDK real do Google (sem rede)\n");
+
+// ── O contrato de nomes que a implementação assume ───────────────────────────
+t("usageMetadata do @google/genai é camelCase, como a implementação assume", () => {
+  const dts = readFileSync(typingsPath(), "utf8");
+  const decl = dts.slice(dts.indexOf("declare class GenerateContentResponseUsageMetadata"));
+  const body = decl.slice(0, decl.indexOf("\n}"));
+  for (const field of [
+    "promptTokenCount", "candidatesTokenCount", "thoughtsTokenCount",
+    "cachedContentTokenCount", "toolUsePromptTokenCount", "totalTokenCount",
+    "promptTokensDetails",
+  ]) {
+    assert.ok(body.includes(`${field}?:`), `campo ${field} sumiu do SDK — a extração de token quebra em silêncio`);
+  }
+});
+
+t("promptTokenCount continua incluindo os tokens cacheados", () => {
+  // A fórmula subtrai `cached` de `prompt`. Se o SDK mudar essa semântica, a
+  // subtração passa a subfaturar — e nada mais no código avisaria.
+  const dts = readFileSync(typingsPath(), "utf8");
+  const i = dts.indexOf("promptTokenCount?:");
+  const doc = dts.slice(Math.max(0, i - 400), i);
+  assert.ok(
+    /also includes the number of tokens in the cached content/i.test(doc),
+    "a doc do campo mudou — revisar `fullPriceInput = prompt - cached` em pricing.js",
+  );
+});
+
+// ── Detecção do cliente real ─────────────────────────────────────────────────
+const raw = new GoogleGenAI({ apiKey: "cb-test-synthetic" });
+
+t("cliente real tem a forma que a detecção procura", () => {
+  assert.strictEqual(raw.constructor.name, "GoogleGenAI");
+  assert.strictEqual(typeof raw.models.generateContent, "function");
+  assert.strictEqual(typeof raw.models.generateContentStream, "function");
+});
+
+t("não colide com a detecção de OpenAI nem de Anthropic", () => {
+  assert.ok(!raw.chat?.completions, "cairia no ramo da OpenAI");
+  assert.ok(!raw.messages?.create,  "cairia no ramo da Anthropic");
+});
+
+// ── Instrumentação ───────────────────────────────────────────────────────────
+// Stub do método original: nenhuma rede, e devolve um usageMetadata realista.
+const tracked = [];
+function makeClient(usageMetadata, { modelVersion = "gemini-2.5-flash" } = {}) {
+  const c = new GoogleGenAI({ apiKey: "cb-test-synthetic" });
+  let seenParams = null;
+  c.models.generateContent = async (params) => {
+    seenParams = params;
+    return { modelVersion, usageMetadata, candidates: [] };
+  };
+  c.models.generateContentStream = async (params) => {
+    seenParams = params;
+    return (async function* () {
+      yield { modelVersion, candidates: [] };
+      yield { modelVersion, usageMetadata, candidates: [] };
+    })();
+  };
+  const wrapped = CloudBrokerAI.wrap(c, { apiKey: "cb-test-key", product: "checkout" });
+  // Intercepta o envio pra inspecionar o evento sem rede.
+  wrapped.trackDeploy = wrapped.trackDeploy; // preserva
+  return { wrapped, getParams: () => seenParams };
+}
+
+// O client.track empurra pra fila e tenta flush em background; aqui trocamos o
+// CloudBrokerClient por captura direta, via monkey-patch do fetch global.
+const realFetch = globalThis.fetch;
+globalThis.fetch = async (url, init) => {
+  try {
+    const body = JSON.parse(init?.body || "{}");
+    for (const ev of (body.events || [])) tracked.push(ev);
+  } catch { /* ignora */ }
+  return { ok: true, status: 200, json: async () => ({ ok: true }) };
+};
+
+await ta("generateContent registra tokens reais e não altera a resposta", async () => {
+  tracked.length = 0;
+  const { wrapped } = makeClient({
+    promptTokenCount: 1000, candidatesTokenCount: 500, totalTokenCount: 1500,
+  });
+  const res = await wrapped.models.generateContent({ model: "gemini-2.5-flash", contents: "oi" });
+  assert.strictEqual(res.modelVersion, "gemini-2.5-flash", "resposta original tem que passar intacta");
+  await new Promise(r => setTimeout(r, 30));
+  const ev = tracked.at(-1);
+  assert.ok(ev, "nenhum evento registrado");
+  assert.strictEqual(ev.provider, "gemini");
+  assert.strictEqual(ev.inputTokens, 1000);
+  assert.strictEqual(ev.outputTokens, 500);
+  assert.strictEqual(ev.costUSD, priceGemini("gemini-2.5-flash", { promptTokenCount: 1000, candidatesTokenCount: 500 }).costUSD);
+});
+
+await ta("thinking tokens entram no output (senão o custo sai muito menor)", async () => {
+  tracked.length = 0;
+  const { wrapped } = makeClient({
+    promptTokenCount: 100, candidatesTokenCount: 50, thoughtsTokenCount: 2000,
+  });
+  await wrapped.models.generateContent({ model: "gemini-2.5-flash", contents: "oi" });
+  await new Promise(r => setTimeout(r, 30));
+  const ev = tracked.at(-1);
+  assert.strictEqual(ev.outputTokens, 2050, "thoughts precisa somar ao output");
+  assert.strictEqual(ev.thoughtsTokens, 2000);
+  const ingenuo = 100 * PRICING.gemini["gemini-2.5-flash"].input + 50 * PRICING.gemini["gemini-2.5-flash"].output;
+  assert.ok(ev.costUSD > ingenuo * 10, "ignorar thoughts subfaturaria em mais de 10x");
+});
+
+await ta("tokens cacheados saem ao preço de cache, não ao preço cheio", async () => {
+  tracked.length = 0;
+  const { wrapped } = makeClient({
+    promptTokenCount: 1000, cachedContentTokenCount: 800, candidatesTokenCount: 100,
+  });
+  await wrapped.models.generateContent({ model: "gemini-2.5-flash", contents: "oi" });
+  await new Promise(r => setTimeout(r, 30));
+  const ev = tracked.at(-1);
+  const r = PRICING.gemini["gemini-2.5-flash"];
+  assert.strictEqual(ev.cachedTokens, 800);
+  assert.ok(Math.abs(ev.costUSD - (200 * r.input + 800 * r.cached + 100 * r.output)) < 1e-9);
+  const cheio = 1000 * r.input + 100 * r.output;
+  assert.ok(ev.costUSD < cheio, "cobrar o prompt inteiro a preço cheio superfaturaria");
+});
+
+await ta("modelo fora da tabela registra tokens sem inventar preço", async () => {
+  tracked.length = 0;
+  const { wrapped } = makeClient(
+    { promptTokenCount: 1000, candidatesTokenCount: 500 },
+    { modelVersion: "gemini-9.9-ultra" },
+  );
+  await wrapped.models.generateContent({ model: "gemini-9.9-ultra", contents: "oi" });
+  await new Promise(r => setTimeout(r, 30));
+  const ev = tracked.at(-1);
+  assert.strictEqual(ev.costUSD, null, "custo tem que ser null, nunca o preço de outro modelo");
+  assert.strictEqual(ev.unpriced, true);
+  assert.strictEqual(ev.inputTokens, 1000, "os tokens continuam sendo registrados");
+  assert.ok(ev.pricingNote?.includes("gemini-9.9-ultra"));
+});
+
+await ta("resposta sem usageMetadata não vira custo zero silencioso", async () => {
+  tracked.length = 0;
+  const { wrapped } = makeClient(undefined);
+  await wrapped.models.generateContent({ model: "gemini-2.5-flash", contents: "oi" });
+  await new Promise(r => setTimeout(r, 30));
+  const ev = tracked.at(-1);
+  assert.strictEqual(ev.totalTokens, 0);
+  assert.strictEqual(ev.costUSD, 0, "sem tokens, zero é o valor correto — o caso perigoso é o modelo desconhecido");
+});
+
+await ta("cbLabel é aceito no params e NÃO vaza pra API do provider", async () => {
+  tracked.length = 0;
+  const { wrapped, getParams } = makeClient({ promptTokenCount: 10, candidatesTokenCount: 5 });
+  await wrapped.models.generateContent({ model: "gemini-2.5-flash", contents: "oi", cbLabel: "checkout:resumo" });
+  await new Promise(r => setTimeout(r, 30));
+  assert.ok(!("cbLabel" in getParams()), "cbLabel vazou pro SDK do Google");
+  assert.strictEqual(tracked.at(-1).label, "checkout:resumo");
+});
+
+await ta("cbLabel também funciona no segundo argumento (convenção dos outros wrappers)", async () => {
+  tracked.length = 0;
+  const { wrapped } = makeClient({ promptTokenCount: 10, candidatesTokenCount: 5 });
+  await wrapped.models.generateContent({ model: "gemini-2.5-flash", contents: "oi" }, { cbLabel: "billing:fatura" });
+  await new Promise(r => setTimeout(r, 30));
+  assert.strictEqual(tracked.at(-1).label, "billing:fatura");
+});
+
+await ta("streaming acumula o usage do chunk final e entrega todos os chunks", async () => {
+  tracked.length = 0;
+  const { wrapped } = makeClient({
+    promptTokenCount: 300, candidatesTokenCount: 200, thoughtsTokenCount: 100,
+  });
+  const stream = await wrapped.models.generateContentStream({ model: "gemini-2.5-flash", contents: "oi" });
+  let chunks = 0;
+  for await (const _ of stream) chunks++;
+  await new Promise(r => setTimeout(r, 30));
+  const ev = tracked.at(-1);
+  assert.strictEqual(chunks, 2, "o consumidor tem que receber os chunks originais");
+  assert.strictEqual(ev.streaming, true);
+  assert.strictEqual(ev.inputTokens, 300);
+  assert.strictEqual(ev.outputTokens, 300, "200 candidates + 100 thoughts");
+});
+
+await ta("erro do provider passa intacto e não é engolido pela instrumentação", async () => {
+  const c = new GoogleGenAI({ apiKey: "cb-test-synthetic" });
+  c.models.generateContent = async () => { throw new Error("429 quota exceeded"); };
+  const wrapped = CloudBrokerAI.wrap(c, { apiKey: "cb-test-key" });
+  await assert.rejects(
+    () => wrapped.models.generateContent({ model: "gemini-2.5-flash", contents: "oi" }),
+    /429 quota exceeded/,
+  );
+});
+
+globalThis.fetch = realFetch;
+
+// ── Preço: casos que o wrapper não exercita ──────────────────────────────────
+const near = (a, b) => Math.abs(a - b) < 1e-9;
+
+t("2.5 Pro troca de faixa acima de 200k tokens de prompt", () => {
+  const base = priceGemini("gemini-2.5-pro", { promptTokenCount: 1000, candidatesTokenCount: 100 });
+  assert.ok(near(base.costUSD, 1000 * 0.00000125 + 100 * 0.00001), "abaixo do corte usa preço base");
+
+  const alto = priceGemini("gemini-2.5-pro", { promptTokenCount: 250000, candidatesTokenCount: 1000 });
+  assert.ok(near(alto.costUSD, 250000 * 0.0000025 + 1000 * 0.000015), "acima de 200k dobra");
+});
+
+t("áudio na entrada é cobrado à parte do texto", () => {
+  const r = PRICING.gemini["gemini-2.5-flash"];
+  const p = priceGemini("gemini-2.5-flash", {
+    promptTokenCount: 1000,
+    promptTokensDetails: [{ modality: "AUDIO", tokenCount: 400 }, { modality: "TEXT", tokenCount: 600 }],
+  });
+  assert.ok(near(p.costUSD, 600 * r.input + 400 * r.audioInput));
+  assert.ok(p.costUSD > 1000 * r.input, "tratar áudio como texto subfaturaria");
+});
+
+t("variante com sufixo casa pelo prefixo MAIS LONGO e é marcada aproximada", () => {
+  const p = priceGemini("gemini-2.5-flash-lite-preview-06", { promptTokenCount: 1000 });
+  assert.strictEqual(p.pricedAs, "gemini-2.5-flash-lite", "não pode cair no 'gemini-2.5-flash', que é mais caro");
+  assert.strictEqual(p.approxPricing, true, "preço de variante não listada tem que sair sinalizado");
+});
+
+t("modelos 1.5/2.0 removidos não são precificados por engano", () => {
+  // Saíram da página oficial; manter preço não verificável seria fabricar custo.
+  for (const legado of ["gemini-1.5-pro", "gemini-1.5-flash", "gemini-2.0-flash"]) {
+    assert.strictEqual(priceGemini(legado, { promptTokenCount: 100 }).costUSD, null, legado);
+  }
+});
+
+console.log(`\n${fail === 0 ? "🎉 TODOS PASSARAM" : "💥 FALHAS"}: ${ok} ok, ${fail} fail`);
+process.exitCode = fail === 0 ? 0 : 1;

package/src/wrapper.js

@@ -4,7 +4,7 @@
  */
 
 import { CloudBrokerClient } from "./client.js";
-import { PRICING } from "./pricing.js";
+import { PRICING, priceGemini } from "./pricing.js";
 import { cbStore } from "./context.js";
 
 export class CloudBrokerAI {
@@ -35,12 +35,18 @@ export class CloudBrokerAI {
     // Adiciona trackDeploy ao cliente wrappado
     client.trackDeploy = cb.trackDeploy.bind(cb);
 
-    // Detecta provider pelo tipo do cliente
+    // Detecta provider pelo tipo do cliente.
+    // O sinal do Gemini é `models.generateContent`, não `models`: o cliente da
+    // OpenAI também tem `.models` (list/retrieve), então checar só o objeto
+    // casaria com o cliente errado.
     const isOpenAI    = client?.constructor?.name === "OpenAI"    || !!client?.chat?.completions;
     const isAnthropic = client?.constructor?.name === "Anthropic" || !!client?.messages?.create;
+    const isGemini    = client?.constructor?.name === "GoogleGenAI"
+                     || typeof client?.models?.generateContent === "function";
 
     if (isOpenAI)    return CloudBrokerAI.#wrapOpenAI(client, cb, { product, team, debug });
     if (isAnthropic) return CloudBrokerAI.#wrapAnthropic(client, cb, { product, team, debug });
+    if (isGemini)    return CloudBrokerAI.#wrapGemini(client, cb, { product, team, debug });
 
     if (debug) console.warn("[CloudBroker] Provider não reconhecido — retornando cliente original.");
     return client;
@@ -254,6 +260,123 @@ export class CloudBrokerAI {
     return client;
   }
 
+  /**
+   * Instrumenta o cliente do @google/genai (`new GoogleGenAI({apiKey})`).
+   *
+   * Diferenças relevantes em relação a OpenAI/Anthropic:
+   *
+   *  - A API é de argumento único (`models.generateContent({model, contents})`),
+   *    sem segundo parâmetro de options. Por isso o `cbLabel` é aceito das duas
+   *    formas: no segundo argumento (convenção dos outros wrappers) e dentro do
+   *    próprio params — neste caso removido antes de repassar, pra nunca vazar
+   *    campo desconhecido para a API do provider.
+   *  - O usage vem em `usageMetadata` (camelCase). Os nomes foram conferidos nos
+   *    tipos do @google/genai@2.15.0, não na doc pública: a doc mostra um
+   *    formato snake_case que pertence a outra superfície da API, e usá-lo
+   *    daria token zero em silêncio.
+   *  - `costUSD` pode ser `null` (modelo fora da tabela de preço). Isso é
+   *    deliberado: registrar tokens sem inventar preço. Quem consome precisa
+   *    olhar `unpriced` — tratar `null` como zero vira "custo real zero".
+   */
+  static #wrapGemini(client, cb, { product, team, debug }) {
+    const models = client.models;
+    if (!models || typeof models.generateContent !== "function") return client;
+
+    // Extrai o cbLabel e devolve os params limpos pra repassar ao provider.
+    const splitLabel = (params, options) => {
+      let label = null, fwd = params;
+      try {
+        label = options?.cbLabel ?? null;
+        if (!label && params && typeof params === "object" && params.cbLabel != null) {
+          label = params.cbLabel;
+        }
+        if (!label) label = cbStore.getStore()?.label ?? null;
+        if (params && typeof params === "object" && "cbLabel" in params) {
+          const { cbLabel: _l, ...rest } = params;
+          fwd = rest;
+        }
+      } catch { /* instrumentação nunca altera a chamada do cliente */ }
+      return { label, fwd };
+    };
+
+    const buildEvent = (model, usage, { label, start, streaming, endpoint }) => {
+      const priced = priceGemini(model, usage || {});
+      return {
+        provider:       "gemini",
+        model,
+        product:        product || null,
+        team:           team    || null,
+        label,
+        inputTokens:    priced.inputTokens,
+        outputTokens:   priced.outputTokens,
+        totalTokens:    priced.totalTokens,
+        costUSD:        priced.costUSD,
+        // Só o Gemini separa esses dois, e são justamente os que mais mexem no
+        // valor: cache barateia ~10x, thinking é cobrado como output.
+        cachedTokens:   priced.cachedTokens,
+        thoughtsTokens: priced.thoughtsTokens,
+        unpriced:       priced.unpriced,
+        pricingNote:    priced.reason,
+        latencyMs:      Date.now() - start,
+        endpoint,
+        streaming:      !!streaming,
+      };
+    };
+
+    // ── generateContent (não-streaming) ───────────────────────────────────────
+    const originalGenerate = models.generateContent.bind(models);
+    models.generateContent = async (params, options) => {
+      const start = Date.now();
+      const { label, fwd } = splitLabel(params, options);
+
+      const res = await originalGenerate(fwd);
+
+      try {
+        const model = res?.modelVersion || params?.model || "unknown";
+        cb.track(buildEvent(model, res?.usageMetadata, {
+          label, start, streaming: false, endpoint: "models.generateContent",
+        }));
+      } catch (err) {
+        if (debug) console.warn("[CloudBroker] track error:", err.message);
+      }
+
+      return res;
+    };
+
+    // ── generateContentStream ────────────────────────────────────────────────
+    if (typeof models.generateContentStream === "function") {
+      const originalStream = models.generateContentStream.bind(models);
+      models.generateContentStream = async (params, options) => {
+        const start = Date.now();
+        const { label, fwd } = splitLabel(params, options);
+
+        const stream = await originalStream(fwd);
+
+        let model = params?.model || "unknown";
+        let usage = null;
+        const onChunk = (chunk) => {
+          if (chunk?.modelVersion) model = chunk.modelVersion;
+          // O usage do Gemini é cumulativo e chega no(s) chunk(s) final(is):
+          // o último que vier é o total da chamada.
+          if (chunk?.usageMetadata) usage = chunk.usageMetadata;
+        };
+        const onDone = () => {
+          try {
+            cb.track(buildEvent(model, usage, {
+              label, start, streaming: true, endpoint: "models.generateContentStream",
+            }));
+          } catch (err) {
+            if (debug) console.warn("[CloudBroker] track error:", err.message);
+          }
+        };
+
+        return CloudBrokerAI.#instrumentStream(stream, onChunk, onDone);
+      };
+    }
+
+    return client;
+  }
+
   /**
    * Registra um deploy para análise de custo
    * Atalho para CloudBrokerClient.trackDeploy() sem precisar envolver um cliente de IA