npm package: @pixley/livechat-sdk
Description: ClavisAI LiveChat SDK - Professional SDK for integrating AI-powered live chat into any frontend
Author: ClavisAI Team
Latest version: 1.0.1

# @clavisai/livechat-sdk

SDK Profissional para integração de LiveChat com IA em qualquer frontend. Oferece autenticação segura, Safety System integrado e widget completo.

## ✨ Recursos

- 🔐 **Autenticação HMAC-SHA256** - Segurança de nível empresarial com proteção contra replay attacks
- 🛡️ **Safety System Integrado** - 5 camadas de validação e proteção de dados
- 🎨 **Widget Customizável** - Interface completa e responsiva
- 🌐 **Multi-platform** - Funciona em React, Vue, Angular, Vanilla JS, e mais
- ⚡ **Tempo Real** - WebSocket para notificações instantâneas
- 📱 **Responsivo** - Adapta-se a todos os dispositivos
- 🌍 **Multi-idioma** - Suporte a PT-BR, EN, ES
- 🔒 **Proteção PII** - Detecção e mascaramento automático de dados sensíveis

## 📦 Instalação

### npm
```bash
npm install @clavisai/livechat-sdk
```

### yarn
```bash
yarn add @clavisai/livechat-sdk
```

### CDN
```html
<script src="https://cdn.jsdelivr.net/npm/@clavisai/livechat-sdk@1.0.0/dist/clavis-livechat.umd.js"></script>
```

## 🚀 Quick Start

### Exemplo 1: Widget Completo (Recomendado)

```typescript
import { ClavisWidget } from '@clavisai/livechat-sdk';

// Inicializa o widget
const widget = new ClavisWidget({
  apiUrl: 'https://api.clavisai.com',
  tenantId: 'seu-tenant-id',
  apiKey: 'sua-api-key', // Opcional para autenticação
  secretKey: 'sua-secret-key', // Opcional para autenticação
  visitorName: 'João Silva',
  visitorEmail: 'joao@example.com',
  language: 'pt-BR',
  primaryColor: '#4f46e5',
  theme: 'light',
  debug: true,
});

// Ouve eventos
widget.on('message_sent', (event) => {
  console.log('Mensagem enviada:', event.data);
});

widget.on('message_received', (event) => {
  console.log('Mensagem recebida:', event.data);
});

widget.on('open', () => {
  console.log('Chat aberto');
});

widget.on('close', () => {
  console.log('Chat fechado');
});

// Controla o widget
widget.open(); // Abre o chat
widget.close(); // Fecha o chat
widget.toggleChat(); // Alterna estado
```

### Exemplo 2: API Simples

```typescript
import { ClavisAPI } from '@clavisai/livechat-sdk';

// Cria instância da API
const api = new ClavisAPI({
  baseUrl: 'https://api.clavisai.com',
  tenantId: 'seu-tenant-id',
  apiKey: 'sua-api-key',
  secretKey: 'sua-secret-key',
});

// Envia mensagem
const response = await api.sendMessage({
  content: 'Olá, gostaria de saber mais sobre os serviços',
  visitorName: 'Maria Santos',
  visitorEmail: 'maria@example.com',
});

// Obtém histórico
const messages = await api.getMessages(response.visitorId);

// Valida mensagem
const validation = await api.validateInput('Meu CPF é 123.456.789-00');
console.log(validation.data.maskedContent); // "Meu CPF é [CPF]"
```

### Exemplo 3: React Integration

```tsx
import { ClavisWidget } from '@clavisai/livechat-sdk';
import { useEffect, useRef } from 'react';

function LiveChat() {
  const widgetRef = useRef<ClavisWidget | null>(null);

  useEffect(() => {
    widgetRef.current = new ClavisWidget({
      apiUrl: 'https://api.clavisai.com',
      tenantId: 'seu-tenant-id',
      visitorName: 'Visitante',
      primaryColor: '#4f46e5',
    });

    return () => {
      widgetRef.current?.destroy();
    };
  }, []);

  const handleOpenChat = () => {
    widgetRef.current?.open();
  };

  return (
    <button onClick={handleOpenChat}>
      Fale Conosco
    </button>
  );
}
```

## 📚 Configuração Completa

```typescript
import { ClavisWidget } from '@clavisai/livechat-sdk';

const widget = new ClavisWidget({
  // Obrigatórios
  apiUrl: 'https://api.clavisai.com',
  tenantId: 'uuid-do-tenant',
  
  // Autenticação (opcional mas recomendado)
  apiKey: 'pk_sua-chave-publica',
  secretKey: 'sk_sua-chave-secreta',
  
  // Visitante
  visitorId: 'uuid-do-visitante', // Opcional, gerado automaticamente
  visitorName: 'João Silva',
  visitorEmail: 'joao@example.com',
  
  // Idioma
  language: 'pt-BR', // pt-BR, en, es
  
  // Widget
  primaryColor: '#4f46e5',
  secondaryColor: '#6366f1',
  theme: 'light', // light, dark, auto
  position: 'bottom-right', // bottom-right, bottom-left, top-right, top-left
  size: 'medium', // small, medium, large
  showFloatingButton: true,
  floatingButtonText: 'Fale Conosco',
  
  // Upload de arquivos
  allowFileUpload: true,
  allowedFileTypes: ['image/*', 'application/pdf', '.doc', '.docx'],
  maxFileSize: 10,
  
  // Outros
  timeout: 30000,
  debug: false,
  autoStart: true,
});

// Eventos do Widget
widget.on('message_sent', (event) => {
  console.log('Mensagem enviada', event.data);
});

widget.on('message_received', (event) => {
  console.log('Mensagem recebida', event.data);
});

widget.on('session_started', (event) => {
  console.log('Sessão iniciada', event.data);
});

widget.on('session_ended', (event) => {
  console.log('Sessão encerrada', event.data);
});

widget.on('agent_online', (event) => {
  console.log('Agente online', event.data);
});

widget.on('agent_offline', (event) => {
  console.log('Agente offline', event.data);
});

widget.on('escalation_request', (event) => {
  console.log('Pedido de escalonamento', event.data);
});

widget.on('open', () => console.log('Chat aberto'));
widget.on('close', () => console.log('Chat fechado'));
widget.on('minimize', () => console.log('Chat minimizado'));
widget.on('maximize', () => console.log('Chat maximizado'));
widget.on('ready', () => console.log('Widget pronto'));
widget.on('state_change', (event) => {
  console.log('Estado alterado', event.data.state);
});
widget.on('error', (event) => {
  console.error('Erro', event.data);
});

// Métodos Públicos
widget.open();
widget.close();
widget.toggleChat();
widget.minimize();
widget.maximize();
await widget.sendMessage('Olá, como posso ajudar?');
widget.destroy();
```

## 🛡️ Safety System

### Validação de Entrada

```typescript
const validation = await api.validateInput('Meu CPF é 123.456.789-00');

console.log(validation.data);
// {
//   isValid: true,
//   detectedLanguage: 'pt',
//   piiDetected: ['cpf'],
//   maskedContent: 'Meu CPF é [CPF]',
//   spamDetected: false,
//   spamScore: 0,
//   sensitiveWordsDetected: false,
//   issues: []
// }
```

### Classificação de Intenção

```typescript
const intent = await api.classifyIntent('Quero falar com um gerente');

console.log(intent);
// {
//   intent: 'escalation_request',
//   confidence: 0.95,
//   message: 'Quero falar com um gerente'
// }
```

### Decisão de Escalonamento

```typescript
const escalation = await api.decideEscalation(
  'Estou muito insatisfeito com o atendimento',
  'Sinto muito pela sua experiência',
  85
);

console.log(escalation);
// {
//   shouldEscalate: true,
//   reason: 'Customer complaint detected',
//   urgency: 'high',
//   suggestions: ['Criar ticket urgente', 'Notificar supervisor']
// }
```

### Métricas

```typescript
const metrics = await api.getSafetyMetrics();

console.log(metrics);
// {
//   totalMessagesProcessed: 1523,
//   totalValidationsPassed: 1450,
//   totalValidationsFailed: 73,
//   totalEscalations: 45,
//   averageQualityScore: 78.5,
//   lastUpdated: '2026-03-19T10:30:00Z'
// }
```

## 🔐 Autenticação

### API Key Authentication

Configure chaves de API no painel do ClavisAI e use no SDK:

```typescript
const widget = new ClavisWidget({
  apiUrl: 'https://api.clavisai.com',
  tenantId: 'seu-tenant-id',
  apiKey: 'pk_sua-chave',
  secretKey: 'sk_sua-chave-secreta',
});
```

### Headers de Autenticação

O SDK automaticamente adiciona os seguintes headers em todas as requisições:

```
X-API-Key: pk_sua-chave
X-API-Timestamp: 1710847800000
X-API-Nonce: uuid-unico
X-API-Signature: hmac-sha256-assinatura
Content-Type: application/json
```

### Segurança

- ✅ **HMAC-SHA256** - Assinatura criptográfica de todas as requisições
- ✅ **Nonces Únicos** - Prevenção contra replay attacks
- ✅ **Timestamp Validation** - Requisições expiram após 5 minutos
- ✅ **Timing-Safe Comparison** - Proteção contra ataques de timing
- ✅ **Data Sanitization** - Limpeza automática de dados sensíveis

## 📖 Tipos e Interfaces

```typescript
// Configuração
interface ClavisConfig {
  apiUrl: string;
  tenantId: string;
  apiKey?: string;
  secretKey?: string;
  visitorId?: string;
  visitorName?: string;
  visitorEmail?: string;
  language?: string;
  timeout?: number;
  debug?: boolean;
  autoStart?: boolean;
}

// Widget Configuration
interface WidgetConfig extends ClavisConfig {
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  primaryColor?: string;
  theme?: 'light' | 'dark' | 'auto';
  showFloatingButton?: boolean;
  allowFileUpload?: boolean;
  // ... mais opções
}

// Message
interface Message {
  id: string;
  visitorId: string;
  type: 'text' | 'image' | 'file' | 'audio' | 'video' | 'location';
  content: string;
  fileUrl?: string;
  fileName?: string;
  fileSize?: number;
  status: 'pending' | 'sent' | 'delivered' | 'read' | 'failed';
  createdAt: number;
  updatedAt: number;
  metadata?: Record<string, unknown>;
}
```

## 🎨 Customização do Widget

### Cores

```typescript
const widget = new ClavisWidget({
  apiUrl: 'https://api.clavisai.com',
  tenantId: 'uuid',
  primaryColor: '#4f46e5',
  secondaryColor: '#6366f1',
});
```

### Posição

```typescript
position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
```

### Tema

```typescript
theme: 'light' | 'dark' | 'auto'
```

### Tamanho

```typescript
size: 'small' | 'medium' | 'large'
```

## 🐛 Tratamento de Erros

```typescript
widget.on('error', (error) => {
  console.error('Erro do SDK:', error);
  console.error('Código:', error.code);
  console.error('Status:', error.statusCode);
});

// Erros comuns
try {
  await widget.sendMessage('Olá');
} catch (error) {
  if (error.code === 'INVALID_TENANT_ID') {
    console.error('Tenant ID inválido');
  } else if (error.code === 'AUTH_ERROR') {
    console.error('Erro de autenticação');
  } else if (error.code === 'NETWORK_ERROR') {
    console.error('Erro de rede');
  }
}
```

## 📊 Métricas e Analytics

```typescript
// Obter métricas do Safety System
const metrics = await api.getSafetyMetrics();

// Log de atividades
widget.on('message_sent', (event) => {
  analytics.track('chat_message_sent', {
    messageLength: event.data.content.length,
    timestamp: Date.now(),
  });
});

widget.on('escalation_request', (event) => {
  analytics.track('chat_escalation', {
    reason: event.data.reason,
    urgency: event.data.urgency,
    timestamp: Date.now(),
  });
});
```

## 🔧 Troubleshooting

### Widget não aparece

1. Verifique se `autoStart: true` está configurado
2. Verifique se `tenantId` é válido
3. Verifique logs de console para erros

### Erro de autenticação

1. Verifique se `apiKey` e `secretKey` estão corretos
2. Verifique se o tenant tem permissões para usar LiveChat
3. Verifique se o timestamp não expirou

### Mensagens não chegando

1. Verifique conexão com WebSocket
2. Verifique se o tenant tem bot Telegram configurado
3. Verifique logs do Safety System

## 📝 License

MIT License - See [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contribuições são bem-vindas! Por favor, leia o [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes.

## 📞 Suporte

- Email: support@clavisai.com
- Docs: https://docs.clavisai.com
- Issues: https://github.com/clavisai/clavisai_backend/issues