cloudbroker-sdk 0.5.0 → 0.7.0

package/example-checkout-app/README.md

@@ -0,0 +1,225 @@
+# CloudBroker SDK Example — Checkout Service
+
+Exemplo funcional de como instrumentar um serviço de checkout com CloudBroker SDK para rastrear custo por feature.
+
+## O Que Faz
+
+Este app de exemplo mostra 5 features sendo rastreadas:
+
+| Feature | Route | Operation | Label |
+|---------|-------|-----------|-------|
+| **Order Processing** | POST /orders | DynamoDB PutItem | `order-processing` |
+| **Invoice Generation** | POST /orders | S3 PutObject | `invoice-generation` |
+| **Order Retrieval** | GET /orders/:id | DynamoDB GetItem | `order-retrieval` |
+| **Fraud Detection** | POST /verify-fraud | DynamoDB GetItem | `fraud-detection` |
+| **Analytics Tracking** | POST /analytics | DynamoDB PutItem | `analytics-tracking` |
+
+Cada feature rastreia seu custo AWS separadamente — depois você pode ver no dashboard CloudBroker quanto cada uma custou.
+
+## Setup (5 minutos)
+
+### 1. Instalar Dependências
+
+```bash
+npm install
+```
+
+### 2. Configurar Credenciais
+
+```bash
+cp .env.example .env
+# Editar .env com suas credenciais AWS + CloudBroker API Key
+```
+
+**Campos obrigatórios:**
+- `AWS_ACCESS_KEY_ID` — sua chave AWS
+- `AWS_SECRET_ACCESS_KEY` — seu secret AWS
+- `CLOUDBROKER_API_KEY` — sua API key CloudBroker (obter em app.cloudbroker.app.br)
+
+### 3. Rodar
+
+```bash
+npm start
+# Saída: ✅ Checkout Example App running on http://localhost:3000
+```
+
+### 4. Testar
+
+```bash
+# Criar pedido (rastreia 2 features)
+curl -X POST http://localhost:3000/orders \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customerId": "cust-123",
+    "items": [{"name": "Widget", "price": 99.99}],
+    "total": 99.99
+  }'
+
+# Resposta:
+# {
+#   "ok": true,
+#   "orderId": "order-1719600600000",
+#   "message": "Order created successfully!..."
+# }
+```
+
+### 5. Ver Custos
+
+1. Acesse https://app.cloudbroker.app.br
+2. Vá a **Custo por Código**
+3. Você verá os labels: `order-processing`, `invoice-generation`, etc
+4. **Nota:** Demora ~5 minutos pro CloudBroker processar os dados
+
+## Exemplos de Uso
+
+### Criar Pedido
+
+```bash
+curl -X POST http://localhost:3000/orders \
+  -H "Content-Type: application/json" \
+  -d '{
+    "customerId": "user-456",
+    "items": [{"name": "Widget A"}, {"name": "Widget B"}],
+    "total": 250.00
+  }'
+```
+
+**O que acontece:**
+1. `order-processing`: DynamoDB registra o pedido
+2. `invoice-generation`: S3 armazena o JSON da invoice
+
+### Recuperar Pedido
+
+```bash
+curl -X GET http://localhost:3000/orders/order-1719600600000
+```
+
+**O que acontece:**
+1. `order-retrieval`: DynamoDB busca o pedido
+2. CloudBroker rastreia o custo dessa operação
+
+### Verificar Fraude
+
+```bash
+curl -X POST http://localhost:3000/verify-fraud \
+  -H "Content-Type: application/json" \
+  -d '{
+    "orderId": "order-123",
+    "customerId": "user-456"
+  }'
+```
+
+**O que acontece:**
+1. `fraud-detection`: DynamoDB consulta perfil do cliente
+2. Retorna score de fraude (0–1)
+
+### Registrar Evento de Analytics
+
+```bash
+curl -X POST http://localhost:3000/analytics \
+  -H "Content-Type: application/json" \
+  -d '{
+    "userId": "user-789",
+    "eventType": "page_view",
+    "data": {"page": "/checkout"}
+  }'
+```
+
+**O que acontece:**
+1. `analytics-tracking`: DynamoDB armazena o evento
+
+## Entendendo os Custos
+
+Depois de ~5 minutos, no dashboard CloudBroker você verá algo assim:
+
+```
+Feature: order-processing
+  Requests: 2
+  Total Cost: $0.000003
+  Cost per Request: $0.0000015
+
+Feature: invoice-generation
+  Requests: 2
+  Total Cost: $0.000002
+  Cost per Request: $0.000001
+
+Feature: order-retrieval
+  Requests: 1
+  Total Cost: $0.00000025
+  Cost per Request: $0.00000025
+
+Feature: fraud-detection
+  Requests: 1
+  Total Cost: $0.00000025
+  Cost per Request: $0.00000025
+
+Feature: analytics-tracking
+  Requests: 2
+  Total Cost: $0.000003
+  Cost per Request: $0.0000015
+```
+
+## Modo Desenvolvimento
+
+Rodar com auto-reload:
+
+```bash
+npm run dev
+```
+
+## Testes E2E
+
+```bash
+npm test
+```
+
+Runs `test/e2e.js` que faz requisições e valida respostas.
+
+## Troubleshooting
+
+### "Nenhum dado aparecendo no dashboard"
+
+1. ✅ API Key configurada?
+   ```bash
+   echo $CLOUDBROKER_API_KEY
+   ```
+
+2. ✅ AWS credenciais válidas? (tente fazer um `aws s3 ls`)
+
+3. ✅ Esperou 5+ minutos? (CloudBroker faz batch)
+
+4. ✅ Fez pelo menos 1 request pro app?
+   ```bash
+   curl http://localhost:3000/health
+   ```
+
+### "Erro 403 na DynamoDB"
+
+- Tabelas `CheckoutOrders`, `CustomerProfiles`, `AnalyticsEvents` não existem na sua conta AWS
+- CloudBroker **não cria tabelas automaticamente** — você precisa criar:
+  ```bash
+  aws dynamodb create-table \
+    --table-name CheckoutOrders \
+    --attribute-definitions AttributeName=orderId,AttributeType=S \
+    --key-schema AttributeName=orderId,KeyType=HASH \
+    --billing-mode PAY_PER_REQUEST
+  ```
+
+### "Erro ao conectar no S3"
+
+- Bucket `checkout-invoices` não existe
+- Crie:
+  ```bash
+  aws s3 mb s3://checkout-invoices-YOUR-UID --region us-east-2
+  ```
+
+## Próximos Passos
+
+- Leia [docs/COST_PER_FEATURE.md](../docs/COST_PER_FEATURE.md) pro guia completo
+- Copie os patterns aqui pro seu próprio backend
+- Cada label representa uma feature — customize conforme suas necessidades
+- Monitore no dashboard CloudBroker qual feature custa mais
+
+## Suporte
+
+Dúvidas? Abra issue em [github.com/rmoura151179/cloudbroker-sdk](https://github.com/rmoura151179/cloudbroker-sdk).

package/example-checkout-app/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "cloudbroker-sdk-example-checkout",
+  "version": "1.0.0",
+  "description": "Exemplo: Rastrear custo por feature com CloudBroker SDK",
+  "type": "module",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "test": "node test/e2e.js"
+  },
+  "keywords": ["cloudbroker", "finops", "cost-tracking"],
+  "author": "CloudBroker",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.18.2",
+    "@aws-sdk/client-s3": "^3.400.0",
+    "@aws-sdk/client-dynamodb": "^3.400.0",
+    "@aws-sdk/lib-dynamodb": "^3.400.0",
+    "cloudbroker-sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/example-checkout-app/server.js

@@ -0,0 +1,209 @@
+import 'dotenv/config';
+import express from 'express';
+import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, PutCommand, GetCommand } from '@aws-sdk/lib-dynamodb';
+import { CloudBrokerCloud } from 'cloudbroker-sdk';
+
+const app = express();
+app.use(express.json());
+
+// ========== AWS Clients Setup (Wrapped) ==========
+
+const s3 = CloudBrokerCloud.wrapAWS(new S3Client({ region: 'us-east-2' }), {
+  apiKey: process.env.CLOUDBROKER_API_KEY,
+  product: process.env.CLOUDBROKER_PRODUCT || 'checkout-example',
+  team: process.env.CLOUDBROKER_TEAM || 'platform',
+});
+
+const dynamodb = CloudBrokerCloud.wrapAWS(
+  DynamoDBDocumentClient.from(new DynamoDBClient({ region: 'us-east-2' })),
+  {
+    apiKey: process.env.CLOUDBROKER_API_KEY,
+    product: process.env.CLOUDBROKER_PRODUCT || 'checkout-example',
+    team: process.env.CLOUDBROKER_TEAM || 'platform',
+  }
+);
+
+// ========== Routes ==========
+
+/**
+ * Health check (no tracking)
+ */
+app.get('/health', (req, res) => {
+  res.json({ ok: true, status: 'healthy', timestamp: new Date().toISOString() });
+});
+
+/**
+ * POST /orders — Create order
+ * Tracks: order-processing (DynamoDB), invoice-generation (S3)
+ */
+app.post('/orders', async (req, res) => {
+  try {
+    const order = {
+      orderId: `order-${Date.now()}`,
+      customerId: req.body.customerId,
+      items: req.body.items || [],
+      total: req.body.total || 0,
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+    };
+
+    // Feature 1: Persistir pedido no DynamoDB
+    await dynamodb.send(
+      new PutCommand({
+        TableName: 'CheckoutOrders',
+        Item: order,
+      }),
+      {
+        cbLabel: 'order-processing', // CloudBroker rastreia como "order-processing"
+      }
+    );
+
+    // Feature 2: Gerar invoice no S3
+    const invoiceJson = JSON.stringify({
+      orderId: order.orderId,
+      customerId: order.customerId,
+      items: order.items,
+      total: order.total,
+      createdAt: order.createdAt,
+    });
+
+    await s3.send(
+      new PutObjectCommand({
+        Bucket: 'checkout-invoices',
+        Key: `invoices/${order.orderId}.json`,
+        Body: invoiceJson,
+        ContentType: 'application/json',
+      }),
+      {
+        cbLabel: 'invoice-generation', // CloudBroker rastreia como "invoice-generation"
+      }
+    );
+
+    res.json({
+      ok: true,
+      orderId: order.orderId,
+      message: 'Order created successfully! Check CloudBroker dashboard for cost breakdown.',
+    });
+  } catch (error) {
+    console.error('[POST /orders] Error:', error.message);
+    res.status(500).json({ ok: false, error: error.message });
+  }
+});
+
+/**
+ * GET /orders/:id — Retrieve order
+ * Tracks: order-retrieval
+ */
+app.get('/orders/:id', async (req, res) => {
+  try {
+    const result = await dynamodb.send(
+      new GetCommand({
+        TableName: 'CheckoutOrders',
+        Key: { orderId: req.params.id },
+      }),
+      {
+        cbLabel: 'order-retrieval',
+      }
+    );
+
+    res.json({
+      ok: true,
+      order: result.Item || null,
+    });
+  } catch (error) {
+    console.error('[GET /orders/:id] Error:', error.message);
+    res.status(500).json({ ok: false, error: error.message });
+  }
+});
+
+/**
+ * POST /verify-fraud — Fraud detection check
+ * Tracks: fraud-detection
+ */
+app.post('/verify-fraud', async (req, res) => {
+  try {
+    const { orderId, customerId } = req.body;
+
+    // Simular: ler perfil de cliente do DynamoDB pra análise
+    const result = await dynamodb.send(
+      new GetCommand({
+        TableName: 'CustomerProfiles',
+        Key: { customerId },
+      }),
+      {
+        cbLabel: 'fraud-detection',
+      }
+    );
+
+    // Mock fraud score
+    const fraudScore = Math.random() * 0.5; // 0–0.5 = low risk
+    const isBlocked = fraudScore > 0.4;
+
+    res.json({
+      ok: true,
+      orderId,
+      customerId,
+      fraud_score: parseFloat(fraudScore.toFixed(2)),
+      is_blocked: isBlocked,
+      message: isBlocked ? 'Order blocked due to fraud risk' : 'Order cleared',
+    });
+  } catch (error) {
+    console.error('[POST /verify-fraud] Error:', error.message);
+    res.status(500).json({ ok: false, error: error.message });
+  }
+});
+
+/**
+ * POST /analytics — Track user action
+ * Tracks: analytics-tracking
+ */
+app.post('/analytics', async (req, res) => {
+  try {
+    const event = {
+      eventId: `event-${Date.now()}`,
+      userId: req.body.userId,
+      eventType: req.body.eventType,
+      data: req.body.data || {},
+      timestamp: new Date().toISOString(),
+    };
+
+    // Store event in DynamoDB
+    await dynamodb.send(
+      new PutCommand({
+        TableName: 'AnalyticsEvents',
+        Item: event,
+      }),
+      {
+        cbLabel: 'analytics-tracking',
+      }
+    );
+
+    res.json({
+      ok: true,
+      eventId: event.eventId,
+      message: 'Analytics event recorded',
+    });
+  } catch (error) {
+    console.error('[POST /analytics] Error:', error.message);
+    res.status(500).json({ ok: false, error: error.message });
+  }
+});
+
+// ========== Server Start ==========
+
+const PORT = parseInt(process.env.PORT || '3000', 10);
+
+app.listen(PORT, () => {
+  console.log(`\n✅ Checkout Example App running on http://localhost:${PORT}`);
+  console.log(`📊 Check costs at: https://app.cloudbroker.app.br → Custo por Código\n`);
+  console.log('Features being tracked:');
+  console.log('  • order-processing (DynamoDB: create order)');
+  console.log('  • invoice-generation (S3: store invoice)');
+  console.log('  • order-retrieval (DynamoDB: fetch order)');
+  console.log('  • fraud-detection (DynamoDB: check profile)');
+  console.log('  • analytics-tracking (DynamoDB: log events)\n');
+});
+
+export default app;

package/example-checkout-app/test/e2e.js

@@ -0,0 +1,97 @@
+import assert from 'assert';
+import fetch from 'node-fetch';
+
+const BASE_URL = 'http://localhost:3000';
+
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`✅ ${name}`);
+  } catch (error) {
+    console.error(`❌ ${name}`);
+    console.error(`   ${error.message}`);
+    process.exit(1);
+  }
+}
+
+async function runTests() {
+  console.log('🧪 Running E2E tests...\n');
+
+  // Test 1: Health check
+  await test('Health check', async () => {
+    const res = await fetch(`${BASE_URL}/health`);
+    assert(res.ok, 'Health check failed');
+    const data = await res.json();
+    assert(data.ok === true, 'Health check returned ok: false');
+  });
+
+  // Test 2: Create order
+  await test('Create order', async () => {
+    const res = await fetch(`${BASE_URL}/orders`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        customerId: 'test-cust-123',
+        items: [{ name: 'Test Widget', price: 99.99 }],
+        total: 99.99,
+      }),
+    });
+    assert(res.ok, `Create order failed: ${res.status}`);
+    const data = await res.json();
+    assert(data.ok === true, 'Create order returned ok: false');
+    assert(data.orderId, 'No orderId in response');
+    global.testOrderId = data.orderId; // Save for next test
+  });
+
+  // Test 3: Get order
+  await test('Get order', async () => {
+    assert(global.testOrderId, 'No orderId from previous test');
+    const res = await fetch(`${BASE_URL}/orders/${global.testOrderId}`);
+    assert(res.ok, `Get order failed: ${res.status}`);
+    const data = await res.json();
+    assert(data.ok === true, 'Get order returned ok: false');
+    // Order might not exist in DynamoDB (local/test setup), but the endpoint should work
+  });
+
+  // Test 4: Verify fraud
+  await test('Verify fraud', async () => {
+    const res = await fetch(`${BASE_URL}/verify-fraud`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        orderId: 'order-test-123',
+        customerId: 'cust-test-456',
+      }),
+    });
+    assert(res.ok, `Verify fraud failed: ${res.status}`);
+    const data = await res.json();
+    assert(data.ok === true, 'Verify fraud returned ok: false');
+    assert(typeof data.fraud_score === 'number', 'No fraud_score in response');
+    assert(data.fraud_score >= 0 && data.fraud_score <= 1, 'fraud_score out of range');
+  });
+
+  // Test 5: Analytics tracking
+  await test('Analytics tracking', async () => {
+    const res = await fetch(`${BASE_URL}/analytics`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        userId: 'user-test-789',
+        eventType: 'page_view',
+        data: { page: '/checkout' },
+      }),
+    });
+    assert(res.ok, `Analytics tracking failed: ${res.status}`);
+    const data = await res.json();
+    assert(data.ok === true, 'Analytics tracking returned ok: false');
+    assert(data.eventId, 'No eventId in response');
+  });
+
+  console.log('\n🎉 All tests passed!');
+  console.log('📊 Check CloudBroker dashboard in ~5 minutes to see the cost breakdown.');
+}
+
+runTests().catch((error) => {
+  console.error('Fatal error:', error.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudbroker-sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "CloudBroker SDK — Token Intelligence & Operational Financial Intelligence",
   "main": "src/index.js",
   "type": "module",
@@ -8,9 +8,19 @@
     ".": "./src/index.js"
   },
   "scripts": {
-    "test": "node src/test.js"
+    "test": "node src/test.js && node src/test-azure-real.js && node src/test-gemini-real.js"
   },
-  "keywords": ["cloudbroker", "finops", "token-intelligence", "openai", "anthropic"],
+  "keywords": [
+    "cloudbroker",
+    "finops",
+    "token-intelligence",
+    "openai",
+    "anthropic"
+  ],
   "license": "MIT",
-  "dependencies": {}
+  "devDependencies": {
+    "@azure/cosmos": "^4.10.0",
+    "@azure/storage-blob": "^12.33.0",
+    "@google/genai": "^2.15.0"
+  }
 }

package/src/client.js

@@ -7,6 +7,17 @@ const DEFAULT_AI_ENDPOINT    = "https://api.cloudbroker.app.br/api/ai/events";
 const DEFAULT_CLOUD_ENDPOINT = "https://api.cloudbroker.app.br/api/cloud/events";
 const DEFAULT_API_BASE       = "https://api.cloudbroker.app.br/api";
 const RETRY_DELAY_MS         = 30_000; // 30s entre retries
+
+/**
+ * Retry que NÃO segura o event loop. Sem `.unref()`, um flush que falha deixa
+ * um timer de 30s pendurado que se reagenda — qualquer processo Node curto
+ * (Lambda, cron, CLI, suíte de teste) que use o SDK nunca encerra sozinho.
+ */
+function scheduleRetry(fn) {
+  const t = setTimeout(fn, RETRY_DELAY_MS);
+  if (typeof t?.unref === "function") t.unref();
+  return t;
+}
 const MAX_QUEUE_SIZE         = 500;    // máximo de eventos em memória
 
 export class CloudBrokerClient {
@@ -37,7 +48,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.5.0",
+        sdkVersion: "0.7.0",
         sentAt: new Date().toISOString(),
       };
       if (this.#cloudQueue.length < MAX_QUEUE_SIZE) {
@@ -69,7 +80,7 @@ export class CloudBrokerClient {
       if (!res.ok) {
         if (this.#debug) console.warn("[CloudBroker] cloud flush failed:", res.status);
         this.#cloudQueue.unshift(...batch);
-        setTimeout(() => { this.#cloudFlushing = false; this.#flushCloud(); }, RETRY_DELAY_MS);
+        scheduleRetry(() => { this.#cloudFlushing = false; this.#flushCloud(); });
         return;
       }
 
@@ -77,7 +88,7 @@ export class CloudBrokerClient {
     } catch (err) {
       this.#cloudQueue.unshift(...batch);
       if (this.#debug) console.warn("[CloudBroker] cloud flush error:", err.message);
-      setTimeout(() => { this.#cloudFlushing = false; this.#flushCloud(); }, RETRY_DELAY_MS);
+      scheduleRetry(() => { this.#cloudFlushing = false; this.#flushCloud(); });
       return;
     }
 
@@ -93,7 +104,7 @@ export class CloudBrokerClient {
     try {
       const payload = {
         ...event,
-        sdkVersion: "0.5.0",
+        sdkVersion: "0.7.0",
         sentAt: new Date().toISOString(),
       };
 
@@ -184,7 +195,7 @@ export class CloudBrokerClient {
         // Recoloca na fila e agenda retry com backoff — nunca recursa na hora,
         // senão um erro persistente (ex: 401) martela o endpoint em loop apertado.
         this.#queue.unshift(...batch);
-        setTimeout(() => { this.#flushing = false; this.#flush(); }, RETRY_DELAY_MS);
+        scheduleRetry(() => { this.#flushing = false; this.#flush(); });
         return;
       }
 
@@ -195,7 +206,7 @@ export class CloudBrokerClient {
       if (this.#debug) console.warn("[CloudBroker] flush error:", err.message);
 
       // Retry em 30s
-      setTimeout(() => { this.#flushing = false; this.#flush(); }, RETRY_DELAY_MS);
+      scheduleRetry(() => { this.#flushing = false; this.#flush(); });
       return;
     }