@poolzin/pool-bot 2026.3.22 → 2026.3.23

package/docs/channels/irc.md

@@ -0,0 +1,332 @@
+# IRC Channel
+
+Integração com servidores IRC para comunicação em tempo real via protocolo IRC tradicional.
+
+## Features
+
+- 🖥️ **Multi-Server** - Conecte a múltiplos servidores IRC
+- 🔐 **SASL Auth** - Autenticação SASL PLAIN
+- 🔁 **Auto-Reconnect** - Reconexão automática
+- 📝 **Multi-Channel** - Entre em múltiplos canais
+- 👥 **User Tracking** - Tracking de usuários
+- 🔒 **TLS/SSL** - Conexões seguras
+
+## Configuração
+
+### 1. Configurar Conexão
+
+```bash
+# Configurar servidor
+poolbot config set channels.irc.host irc.libera.chat
+poolbot config set channels.irc.port 6697
+poolbot config set channels.irc.tls true
+
+# Nickname do bot
+poolbot config set channels.irc.nick poolbot
+
+# Canais para entrar
+poolbot config set channels.irc.channels '["#poolbot","#test"]'
+
+# Habilitar canal
+poolbot config set channels.irc.enabled true
+```
+
+### 2. Configurar SASL (Opcional)
+
+```bash
+# NickServ credentials
+poolbot config set channels.irc.sasl.account your-nick
+poolbot config set channels.irc.sasl.password your-password
+```
+
+### 3. Configurar Senha do Server (Opcional)
+
+```bash
+poolbot config set channels.irc.password serverpass
+```
+
+## Uso
+
+### Conectar
+
+```typescript
+import { createIRCChannel } from '@poolbot/irc'
+
+const channel = createIRCChannel({
+  host: 'irc.libera.chat',
+  port: 6697,
+  nick: 'poolbot',
+  channels: ['#poolbot', '#test'],
+  tls: true,
+  sasl: {
+    account: 'poolbot',
+    password: 'secret',
+  },
+})
+
+await channel.connect()
+```
+
+### Enviar Mensagem
+
+```typescript
+// Enviar para canal
+await channel.sendMessage({
+  text: 'Hello IRC!',
+  to: '#poolbot',
+})
+
+// Enviar para usuário
+await channel.sendMessage({
+  text: 'Hello!',
+  to: 'username',
+})
+```
+
+### Receber Mensagens
+
+```typescript
+await channel.receiveMessages((msg) => {
+  console.log(`[${msg.to}] ${msg.from}: ${msg.text}`)
+})
+```
+
+### Entrar/Sair de Canais
+
+```typescript
+// Entrar em canal
+await channel.joinChannel('#newchannel')
+
+// Sair de canal
+await channel.leaveChannel('#oldchannel')
+```
+
+### Obter Usuários
+
+```typescript
+const presences = await channel.getPresences()
+console.log(presences)
+// [{ channelId: '#poolbot', userId: 'user1', status: 'online' }, ...]
+```
+
+## Config Options
+
+```typescript
+type IRCConfig = {
+  host: string              // Servidor IRC
+  port: number              // Porta (6667 ou 6697 para TLS)
+  nick: string              // Nickname do bot
+  channels: string[]        // Canais para entrar
+  password?: string         // Senha do servidor
+  sasl?: {
+    account: string         // NickServ account
+    password: string        // NickServ password
+  }
+  tls?: boolean             // Usar TLS/SSL
+}
+```
+
+## Auto-Reconnect
+
+O canal IRC reconecta automaticamente:
+
+```typescript
+{
+  auto_reconnect: true,
+  auto_reconnect_wait: 10,         // Segundos
+  max_reconnect_attempts: 5,       // Tentativas máximas
+}
+```
+
+## Comandos IRC
+
+### Comandos do Bot
+
+```
+!join #channel     - Entrar em canal
+!part #channel     - Sair de canal
+!nick newnick      - Mudar nickname
+!whois user        - Whois de usuário
+!channels          - Listar canais
+```
+
+### Comandos IRC Padrão
+
+```
+/join #channel     - Entrar em canal
+/part #channel     - Sair de canal
+/nick newnick      - Mudar nick
+/whois user        - Whois
+/msg user text     - Mensagem privada
+```
+
+## Exemplos
+
+### Bot de Boas-Vindas
+
+```typescript
+await channel.receiveMessages((msg) => {
+  if (msg.text.includes('join')) {
+    channel.sendMessage({
+      to: msg.from,
+      text: `Bem-vindo ${msg.from}!`,
+    })
+  }
+})
+```
+
+### Resposta a Comandos
+
+```typescript
+await channel.receiveMessages((msg) => {
+  if (msg.text.startsWith('!hora')) {
+    const hora = new Date().toLocaleTimeString()
+    channel.sendMessage({
+      to: msg.to,
+      text: `São ${hora}`,
+    })
+  }
+})
+```
+
+### Bridge com Outros Canais
+
+```typescript
+// Bridge IRC <-> Telegram
+await channel.receiveMessages((msg) => {
+  if (msg.to === '#bridge') {
+    telegramChannel.sendMessage({
+      text: `[IRC] ${msg.from}: ${msg.text}`,
+    })
+  }
+})
+```
+
+## Troubleshooting
+
+### Conexão Recusada
+
+```
+Error: Connection refused
+```
+
+**Solução:**
+- Verificar host/porta
+- Testar com telnet: `telnet irc.server.com 6667`
+- Verificar firewall
+
+### Nickname já em uso
+
+```
+Erroneous nickname
+```
+
+**Solução:**
+- Mudar nickname: `poolbot config set channels.irc.nick poolbot_`
+- Registrar nick no NickServ
+
+### Não consegue entrar em canais
+
+```
+Cannot join channel
+```
+
+**Solução:**
+- Verificar se canal existe
+- Verificar permissões (canais +i, +k)
+- Identificar-se antes: `/msg NickServ IDENTIFY password`
+
+### TLS/SSL Errors
+
+```
+SSL/TLS handshake failed
+```
+
+**Solução:**
+- Usar porta correta (6697 para TLS)
+- Verificar certificados
+- Desabilitar TLS para teste: `tls: false`
+
+## Servidores Recomendados
+
+### Libera Chat (Open Source)
+```
+host: irc.libera.chat
+port: 6697 (TLS) / 6667 (plain)
+tls: true
+```
+
+### Freenode (Legacy)
+```
+host: irc.freenode.net
+port: 6697 (TLS)
+tls: true
+```
+
+### OFTC
+```
+host: irc.oftc.net
+port: 6697 (TLS)
+tls: true
+```
+
+## Security
+
+### Best Practices
+
+1. **Sempre use TLS** quando disponível
+2. **Registre seu nick** no NickServ
+3. **Use SASL** em vez de enviar senha no comando
+4. **Não envie senhas** em canais públicos
+5. **Limite rate** de mensagens
+
+### Configuração Segura
+
+```typescript
+{
+  host: 'irc.libera.chat',
+  port: 6697,        // TLS port
+  tls: true,         // Always use TLS
+  sasl: {            // SASL auth
+    account: 'poolbot',
+    password: 'secret',
+  },
+  nick: 'poolbot',
+  channels: ['#poolbot'],
+}
+```
+
+## API Reference
+
+### Methods
+
+- `connect()` - Conectar ao servidor
+- `disconnect()` - Desconectar (QUIT)
+- `sendMessage(message)` - Enviar mensagem
+- `receiveMessages(callback)` - Configurar receiver
+- `getPresences()` - Obter usuários dos canais
+- `joinChannel(channel)` - Entrar em canal
+- `leaveChannel(channel)` - Sair de canal
+- `getStatus()` - Status da conexão
+
+### Events
+
+- `connect` - Conectado ao servidor
+- `disconnect` - Desconectado
+- `message` - Nova mensagem
+- `notice` - Notice recebido
+- `error` - Erro
+- `join` - Usuário entrou no canal
+- `part` - Usuário saiu do canal
+
+## Arquivos Relacionados
+
+- `extensions/irc/src/irc-channel.ts` - Implementação
+- `extensions/irc/src/index.ts` - Entry point
+- `extensions/irc/package.json` - Dependências (irc-framework)
+
+## Links Relacionados
+
+- [IRC Protocol](https://www.irc.org/tech_docs/protocol.html)
+- [IRCv3 Extensions](https://ircv3.net/)
+- [irc-framework Docs](https://github.com/kiwiirc/irc-framework)