npm package: @ko-ia/voice-sdk
Description: Koia Voice SDK - Cliente de voz para integração com agentes Koia
Author: Koia
Latest version: 2.0.0

# Koia Voice SDK

[![npm version](https://img.shields.io/npm/v/@koia/voice-sdk.svg)](https://www.npmjs.com/package/@koia/voice-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Cliente de voz web para integração com agentes Koia. Este SDK permite criar experiências de voz interativas usando a plataforma Koia com suporte completo a TypeScript.

## Características

- ✅ **Somente áudio**: Otimizado para experiências de voz sem vídeo
- 🎙️ **Cancelamento de ruído**: Processamento de áudio avançado integrado
- 📱 **Suporte mobile**: Funciona em dispositivos móveis e desktop
- 🔊 **Controle de dispositivos**: Gerenciamento de microfones e alto-falantes
- 📊 **Análise em tempo real**: Eventos de volume, fala e qualidade de rede
- 🎯 **TypeScript**: Totalmente tipado para melhor experiência de desenvolvimento
- 🔄 **Event-driven**: Sistema robusto de eventos para controle completo

## Instalação

### Via npm (quando publicado)

```bash
# npm
npm install @koia/voice-sdk

# yarn
yarn add @koia/voice-sdk

# pnpm
pnpm add @koia/voice-sdk
```

### Instalação Local (desenvolvimento)

#### Opção 1: Link Local (Recomendado)

No diretório do SDK:
```bash
# Instalar dependências e compilar
npm install
npm run build

# Criar link global
npm link
```

No seu projeto:
```bash
# Usar o SDK linkado
npm link @koia/voice-sdk
```

#### Opção 2: Instalação por Caminho

```bash
# Instalar diretamente do diretório local
npm install file:caminho/para/sdk-voice-web-client

# Exemplo:
npm install file:../sdk-voice-web-client
```

#### Opção 3: Import Direto

Após compilar (`npm run build`), importe diretamente:
```typescript
// Import do arquivo compilado
import KoiaVoiceClient from './caminho/para/dist/index.js';
```

## Uso Básico

### Importação

```typescript
import KoiaVoiceClient, { 
  KoiaVoiceConfig, 
  KoiaAgentOverrides,
  KOIA_VOICE_EVENTS 
} from '@koia/voice-sdk';

// ou importação alternativa
import { createKoiaVoiceClient } from '@koia/voice-sdk';
```

### Configuração Inicial

```typescript
const config: KoiaVoiceConfig = {
  apiToken: 'seu-token-api-koia',
  baseUrl: 'https://api.ko-ia.com', // opcional, padrão para dev
  audioConfig: {
    enableNoiseCancellation: true,
    enableEchoCancellation: true,
    startAudioOff: false
  },
  advanced: {
    avoidEval: true,
    alwaysIncludeMicInPermissionPrompt: false
  }
};

const voiceClient = new KoiaVoiceClient(config);
```

### Exemplo Completo

```typescript
import KoiaVoiceClient, { 
  KoiaVoiceConfig, 
  KOIA_VOICE_EVENTS 
} from '@koia/voice-sdk';

// Configuração
const config: KoiaVoiceConfig = {
  apiToken: 'seu-token-aqui',
  audioConfig: {
    enableNoiseCancellation: true,
    startAudioOff: false
  }
};

// Criar cliente
const client = new KoiaVoiceClient(config);

// Event listeners
client.on(KOIA_VOICE_EVENTS.CALL_START, () => {
  console.log('Sessão de voz iniciada!');
});

client.on(KOIA_VOICE_EVENTS.MESSAGE, (message) => {
  console.log('Mensagem recebida:', message);
});

client.on(KOIA_VOICE_EVENTS.VOLUME_LEVEL, (level) => {
  console.log('Nível de volume:', level);
});

client.on(KOIA_VOICE_EVENTS.ERROR, (error) => {
  console.error('Erro:', error);
});

client.on(KOIA_VOICE_EVENTS.CALL_END, () => {
  console.log('Sessão encerrada');
});

// Iniciar sessão
async function iniciarSessao() {
  try {
    const session = await client.startVoiceSession('seu-agent-id');
    console.log('Sessão criada:', session);
  } catch (error) {
    console.error('Erro ao iniciar:', error);
  }
}

// Controles durante a sessão
function controlarSessao() {
  // Fazer o agente falar
  client.speakText('Olá! Como posso ajudar você hoje?');
  
  // Silenciar/ativar microfone
  client.setMicrophoneEnabled(false); // silenciar
  client.setMicrophoneEnabled(true);  // ativar
  
  // Enviar mensagem de texto
  client.sendMessage({
    role: 'user',
    content: 'Esta é uma mensagem de texto'
  });
  
  // Verificar status
  console.log('Sessão ativa:', client.isSessionActive());
  console.log('Microfone ativo:', client.isMicrophoneEnabled());
}

// Encerrar sessão
function encerrarSessao() {
  client.endVoiceSession();
}

// Iniciar
iniciarSessao();
```

## API Reference

### KoiaVoiceClient

#### Construtor

```typescript
new KoiaVoiceClient(config: KoiaVoiceConfig)
```

#### Métodos Principais

##### `startVoiceSession(agentId: string, overrides?: KoiaAgentOverrides): Promise<KoiaVoiceSession>`

Inicia uma nova sessão de voz com o agente especificado.

```typescript
const session = await client.startVoiceSession('agent-123', {
  customInstructions: 'Seja mais formal nas respostas',
  voiceSettings: {
    speed: 1.1,
    volume: 0.8
  }
});
```

##### `endVoiceSession(): void`

Encerra a sessão de voz atual.

```typescript
client.endVoiceSession();
```

##### `speakText(text: string, options?: SpeakOptions): void`

Faz o agente falar um texto específico.

```typescript
client.speakText('Olá, mundo!', {
  endSessionAfter: false,
  interruptionsEnabled: true
});
```

##### `sendMessage(message: KoiaMessagePayload): void`

Envia uma mensagem de texto para o agente.

```typescript
client.sendMessage({
  role: 'user',
  content: 'Como está o tempo hoje?',
  timestamp: new Date().toISOString()
});
```

##### `setMicrophoneEnabled(enabled: boolean): void`

Controla o estado do microfone.

```typescript
client.setMicrophoneEnabled(false); // silenciar
client.setMicrophoneEnabled(true);  // ativar
```

##### `isMicrophoneEnabled(): boolean`

Verifica se o microfone está ativo.

```typescript
const isActive = client.isMicrophoneEnabled();
```

##### `isSessionActive(): boolean`

Verifica se há uma sessão ativa.

```typescript
const isActive = client.isSessionActive();
```

#### Métodos de Dispositivos de Áudio

##### `getAudioDevices(): Promise<{microphones: MediaDeviceInfo[], speakers: MediaDeviceInfo[]}>`

Obtém lista de dispositivos de áudio disponíveis.

```typescript
const devices = await client.getAudioDevices();
console.log('Microfones:', devices.microphones);
console.log('Alto-falantes:', devices.speakers);
```

##### `setAudioInputDevice(deviceId: string): Promise<void>`

Define o dispositivo de entrada de áudio.

```typescript
await client.setAudioInputDevice('device-id-123');
```

##### `setAudioOutputDevice(deviceId: string): Promise<void>`

Define o dispositivo de saída de áudio.

```typescript
await client.setAudioOutputDevice('device-id-456');
```

#### Métodos de Diagnóstico

##### `getDiagnosticInfo(): any`

Obtém informações de diagnóstico da sessão.

```typescript
const diagnostics = client.getDiagnosticInfo();
console.log('Diagnósticos:', diagnostics);
```

##### `getNetworkStats(): any`

Obtém estatísticas de rede da sessão atual.

```typescript
const stats = client.getNetworkStats();
console.log('Estatísticas de rede:', stats);
```

### Eventos

O SDK emite vários eventos que você pode escutar:

```typescript
// Eventos de sessão
client.on('call-start', () => {});
client.on('call-end', () => {});

// Eventos de áudio
client.on('speech-start', () => {});
client.on('speech-end', () => {});
client.on('volume-level', (level: number) => {});

// Eventos de mensagem
client.on('message', (message: any) => {});

// Eventos de erro
client.on('error', (error: any) => {});

// Eventos de rede
client.on('network-quality-change', (event: any) => {});
client.on('network-connection', (event: any) => {});

// Eventos de progresso
client.on('call-start-progress', (event: CallStartProgressEvent) => {});
client.on('call-start-success', (event: CallStartSuccessEvent) => {});
client.on('call-start-failed', (event: CallStartFailedEvent) => {});
```

### Tipos TypeScript

#### KoiaVoiceConfig

```typescript
interface KoiaVoiceConfig {
  apiToken: string;
  baseUrl?: string;
  audioConfig?: {
    enableNoiseCancellation?: boolean;
    enableEchoCancellation?: boolean;
    audioSource?: boolean;
    startAudioOff?: boolean;
  };
  advanced?: {
    avoidEval?: boolean;
    alwaysIncludeMicInPermissionPrompt?: boolean;
  };
}
```

#### KoiaAgentOverrides

```typescript
interface KoiaAgentOverrides {
  customInstructions?: string;
  voiceSettings?: {
    speed?: number;
    pitch?: number;
    volume?: number;
    voiceId?: string;
  };
  variables?: Record<string, any>;
  responseConfig?: {
    maxTokens?: number;
    temperature?: number;
    enableInterruptions?: boolean;
  };
}
```

#### KoiaMessagePayload

```typescript
interface KoiaMessagePayload {
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp?: string;
}
```

## Desenvolvimento

### Estrutura do Projeto

```
sdk-voice-web-client/
├── src/
│   └── index.ts          # Código principal do SDK
├── dist/                 # Build compilado
├── package.json         # Configurações do projeto
├── tsconfig.json        # Configurações TypeScript
└── README.md           # Esta documentação
```

### Scripts de Desenvolvimento

```bash
# Compilar o projeto
npm run build

# Modo de desenvolvimento (watch)
npm run dev

# Limpar arquivos de build
npm run clean
```

### Build

O projeto usa [tsup](https://tsup.egoist.sh/) para build:

```bash
npm run build
```

Gera arquivos nos formatos ESM e CJS em `dist/`:
- `dist/index.js` (ESM)
- `dist/index.d.ts` (declarações TypeScript)

## Suporte

- 📧 **Email**: suporte@ko-ia.com
- 📚 **Documentação**: [docs.ko-ia.com](https://docs.ko-ia.com)
- 🐛 **Issues**: [GitLab Issues](https://gitlab.com/intellectia/platform/sdk-voice-web-client/-/issues)

## Licença

MIT © Koia

## Autor

**Koia** - Plataforma de agentes de voz inteligentes