api-stats-logger/README.md

SDK completo de logging e monitoramento de APIs com nova estrutura de logs organizada, auto-instrumentação, dashboard em tempo real e CLI para configuração automática. Suporta logs estruturados por contexto (HTTP, business, security, system) com campos op

# API Stats Logger

[![npm version](https://badge.fury.io/js/api-stats-logger.svg)](https://badge.fury.io/js/api-stats-logger)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**SDK profissional para logging e monitoramento de APIs em Node.js com instrumentação automática.**

## 🚀 Instalação

```bash
npm install api-stats-logger
```

## ⚡ Início Rápido

### 🔐 Login Persistente (Novo!)

O SDK agora mantém você logado automaticamente entre sessões:

```bash
npx api-stats-logger
# Primeira vez: faça login (Google OAuth ou email/senha)
# Próximas vezes: login automático! 🎉
```

**Funcionalidades do Login Persistente:**
- ✅ **Armazenamento seguro** no keychain do sistema
- ✅ **Modo offline** com cache inteligente
- ✅ **Sincronização automática** quando voltar online
- ✅ **Validação contínua** de credenciais
- ✅ **Migração automática** de configurações antigas

### Configuração Automática (Recomendado)

```bash
npx api-stats-init
```

Este comando irá:
- ✅ Configurar automaticamente o projeto
- ✅ Gerar API key
- ✅ Criar arquivos de configuração
- ✅ Detectar seu framework automaticamente
- ✅ **Salvar credenciais** para próximas execuções

### Configuração Manual

```javascript
const ApiStatsLogger = require('api-stats-logger');

const logger = new ApiStatsLogger({
  apiKey: process.env.API_STATS_API_KEY,
  service: 'minha-api',
  environment: 'production'
});

// Logging manual
logger.info('Usuário logado', { userId: 123 });
logger.error('Erro no banco', { error: 'timeout' });
```

## 🔧 Frameworks Suportados

### Express.js

```javascript
const express = require('express');
const ApiStatsLogger = require('api-stats-logger');

const app = express();
const logger = new ApiStatsLogger();

// Middleware automático
app.use(ApiStatsLogger.expressMiddleware({ logger }));

app.listen(3000);
```

### NestJS

```javascript
// Adicione no main.ts
import { ApiStatsLogger } from 'api-stats-logger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  const logger = new ApiStatsLogger();
  app.use(ApiStatsLogger.nestMiddleware({ logger }));
  
  await app.listen(3000);
}
```

### Fastify & Koa

```javascript
// Fastify
fastify.register(ApiStatsLogger.fastifyPlugin());

// Koa
app.use(ApiStatsLogger.koaMiddleware());
```

## 📊 Recursos

- 🚀 **Auto-instrumentação** - Captura automática de requests/responses
- 📈 **Métricas de Performance** - Response time, throughput, error rate
- 🔍 **Rastreamento Distribuído** - Trace IDs para debugging
- 🛡️ **Segurança** - Headers sensíveis automaticamente filtrados
- 📦 **Zero Configuração** - Funciona out-of-the-box
- 🔄 **Retry Logic** - Resiliente a falhas de rede
- 📱 **Dashboard** - Interface web para visualização

## ⚙️ Configuração Avançada

```javascript
const logger = new ApiStatsLogger({
  apiKey: process.env.API_STATS_API_KEY,
  service: 'minha-api',
  environment: 'production',
  
  // Performance
  batchSize: 50,
  flushInterval: 5000,
  maxRetries: 3,
  
  // Recursos
  captureErrors: true,
  capturePerformance: true,
  
  // Segurança
  captureBody: false,
  captureHeaders: false
});
```

## 🔒 Segurança

O SDK automaticamente filtra headers sensíveis:
- `authorization`
- `cookie`
- `x-api-key`
- `x-auth-token`

## 📚 Exemplos

### Logging de Operações

```javascript
async function processPayment(paymentData) {
  const operationId = `payment_${Date.now()}`;
  
  logger.info('Payment started', { operationId, amount: paymentData.amount });
  
  try {
    const result = await paymentGateway.process(paymentData);
    logger.info('Payment completed', { operationId, paymentId: result.id });
    return result;
  } catch (error) {
    logger.error('Payment failed', { operationId, error: error.message });
    throw error;
  }
}
```

### Middlewares Customizados

```javascript
// Express middleware customizado
app.use(ApiStatsLogger.expressMiddleware({
  logger,
  captureBody: false,
  captureHeaders: false,
  skipPaths: ['/health', '/metrics']
}));
```

## 🔧 Variáveis de Ambiente

```bash
# Obrigatório
API_STATS_API_KEY=sua-api-key-aqui

# Opcionais
API_STATS_SERVICE=minha-api
API_STATS_ENVIRONMENT=production
API_STATS_URL=https://api.exemplo.com/logs
API_STATS_ENABLED=true
API_STATS_BATCH_SIZE=20
API_STATS_FLUSH_INTERVAL=5000
```

## 📈 Métricas Coletadas

- **HTTP Requests**: Response time, status codes, throughput
- **Erros**: Stack traces, frequência, categorização
- **Performance**: Uso de recursos, uptime
- **Operações de Negócio**: Transações, conversões

## 🔐 Sistema de Login Persistente

### Funcionalidades Avançadas

O SDK v2.3.7+ inclui um sistema robusto de login persistente:

```bash
# Primeira execução - fazer login
npx api-stats-logger
# Escolha: Google OAuth, Email/Senha ou API Key

# Próximas execuções - login automático!
npx api-stats-logger
# ✅ Logado automaticamente
```

### Armazenamento Seguro

- **🔐 Keychain do Sistema**: Windows Credential Manager, macOS Keychain, Linux Keyring
- **📁 Arquivo Local Seguro**: Fallback com permissões restritas (0600)
- **🧹 Limpeza Automática**: Credenciais inválidas são removidas automaticamente

### Modo Offline

```bash
# Trabalhe offline com dados em cache
npx api-stats-logger
# 📦 Usando dados em cache (modo offline)
```

**Funcionalidades Offline:**
- ✅ Visualizar projetos em cache
- ✅ Configurar projetos existentes  
- ✅ Gerar arquivos de configuração
- ❌ Criar novos projetos (requer conexão)

### Comandos Úteis

```bash
# Demonstrar funcionalidades de login persistente
npm run demo:login

# Teste completo do sistema
npm run demo:full

# Ver estatísticas de cache
npm run demo:stats

# Limpar cache e credenciais
npm run clear:cache
```

### Gerenciamento de Credenciais

```javascript
const SecureStorage = require('api-stats-logger/secure-storage');
const storage = new SecureStorage();

// Verificar se está logado
const credentials = await storage.getCredentials();
console.log('Logado:', !!credentials);

// Limpar credenciais
await storage.clearCredentials();
```

### Segurança

- **🔒 Criptografia**: Dados sensíveis protegidos pelo keychain do SO
- **⏰ Expiração**: Tokens validados automaticamente
- **🚫 Isolamento**: Cada usuário tem seus próprios dados
- **🔄 Migração**: Credenciais antigas migradas automaticamente

📖 **Documentação completa**: [PERSISTENT_LOGIN.md](./PERSISTENT_LOGIN.md)

## 🆘 Suporte

- **Documentação**: [GitHub](https://github.com/api-stats-logger)
- **Issues**: [GitHub Issues](https://github.com/api-stats-logger/issues)
- **Email**: support@api-stats.com

## 📜 Licença

MIT License - veja [LICENSE](LICENSE) para detalhes.

---

**Desenvolvido com ❤️ para desenvolvedores Node.js**