@poolzin/pool-bot 2026.3.22 → 2026.3.24

package/docs/channels/nostr.md

@@ -1,235 +1,322 @@
----
-summary: "Nostr DM channel via NIP-04 encrypted messages"
-read_when:
-  - You want Pool Bot to receive DMs via Nostr
-  - You're setting up decentralized messaging
----
-# Nostr
+# Nostr Channel
 
-**Status:** Optional plugin (disabled by default).
+Integração com o protocolo Nostr para comunicação descentralizada e resistente à censura.
 
-Nostr is a decentralized protocol for social networking. This channel enables Pool Bot to receive and respond to encrypted direct messages (DMs) via NIP-04.
+## Features
 
-## Install (on demand)
+- 🔐 **Criptografia** - Chaves públicas/privadas
+- 📡 **Multi-Relay** - Conecte a múltiplos relays
+- ✉️ **DMs Criptografadas** - NIP-04 direct messages
+- 📝 **Text Notes** - Publicar notas (Kind 1)
+- 👤 **Perfil** - Metadata de usuário (Kind 0)
+- 🔍 **Subscribe** - Inscrição em eventos
+- ⚡ **Tempo Real** - Atualizações em tempo real
 
-### Onboarding (recommended)
+## O que é Nostr?
 
-- The onboarding wizard (`poolbot onboard`) and `poolbot channels add` list optional channel plugins.
-- Selecting Nostr prompts you to install the plugin on demand.
+Nostr (Notes and Other Stuff Transmitted by Relays) é um protocolo descentralizado para comunicação resistente à censura.
 
-Install defaults:
+### Conceitos Chave
 
-- **Dev channel + git checkout available:** uses the local plugin path.
-- **Stable/Beta:** downloads from npm.
+- **Relays** - Servidores que retransmitem mensagens
+- **Keys** - Chaves criptográficas (pública/privada)
+- **Events** - Mensagens assinadas criptograficamente
+- **Kinds** - Tipos de eventos (0=perfil, 1=nota, 4=DM)
 
-You can always override the choice in the prompt.
+## Configuração
 
-### Manual install
+### 1. Gerar Chaves
 
 ```bash
-poolbot plugins install @poolbot/nostr
+# Gerar novo par de chaves
+poolbot nostr generate-keys
+
+# Ou usar chaves existentes
+poolbot config set channels.nostr.privateKey YOUR_HEX_KEY
+poolbot config set channels.nostr.publicKey YOUR_HEX_PUBKEY
 ```
 
-Use a local checkout (dev workflows):
+### 2. Configurar Relays
 
 ```bash
-poolbot plugins install --link <path-to-poolbot>/extensions/nostr
-```
+# Adicionar relays
+poolbot config set channels.nostr.relays '["wss://relay.damus.io","wss://nos.lol","wss://relay.nostr.band"]'
 
-Restart the Gateway after installing or enabling plugins.
-
-## Quick setup
+# Habilitar canal
+poolbot config set channels.nostr.enabled true
+```
 
-1) Generate a Nostr keypair (if needed):
+### 3. Configurar Perfil (Opcional)
 
 ```bash
-# Using nak
-nak key generate
+poolbot config set channels.nostr.profile '{"name":"Pool Bot","about":"AI Bot on Nostr","picture":"https://..."}'
 ```
 
-2) Add to config:
+## Uso
 
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}"
-    }
-  }
-}
+### Publicar Nota
+
+```typescript
+import { createNostrChannel } from '@poolbot/nostr'
+
+const channel = createNostrChannel({
+  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+  privateKey: 'your-hex-private-key', // Opcional para apenas ler
+})
+
+await channel.connect()
+
+// Publicar nota
+await channel.sendMessage({
+  text: 'Hello Nostr! 🚀',
+})
 ```
 
-3) Export the key:
+### Direct Message (DM)
 
-```bash
-export NOSTR_PRIVATE_KEY="nsec1..."
-```
-
-4) Restart the Gateway.
-
-## Configuration reference
-
-| Key | Type | Default | Description |
-| --- | --- | --- | --- |
-| `privateKey` | string | required | Private key in `nsec` or hex format |
-| `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | Relay URLs (WebSocket) |
-| `dmPolicy` | string | `pairing` | DM access policy |
-| `allowFrom` | string[] | `[]` | Allowed sender pubkeys |
-| `enabled` | boolean | `true` | Enable/disable channel |
-| `name` | string | - | Display name |
-| `profile` | object | - | NIP-01 profile metadata |
-
-## Profile metadata
-
-Profile data is published as a NIP-01 `kind:0` event. You can manage it from the Control UI (Channels -> Nostr -> Profile) or set it directly in config.
-
-Example:
-
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "profile": {
-        "name": "poolbot",
-        "displayName": "Pool Bot",
-        "about": "Personal assistant DM bot",
-        "picture": "https://example.com/avatar.png",
-        "banner": "https://example.com/banner.png",
-        "website": "https://example.com",
-        "nip05": "poolbot@example.com",
-        "lud16": "poolbot@example.com"
-      }
-    }
-  }
-}
+```typescript
+// Enviar DM criptografada (NIP-04)
+await channel.sendDirectMessage(
+  'recipient-public-key-hex',
+  'Secret message!'
+)
 ```
 
-Notes:
+### Receber Mensagens
 
-- Profile URLs must use `https://`.
-- Importing from relays merges fields and preserves local overrides.
+```typescript
+// Subscribe a todas as menções
+await channel.receiveMessages((msg) => {
+  console.log(`From ${msg.from}: ${msg.text}`)
+})
 
-## Access control
+// Subscribe com filtro
+await channel.subscribe({
+  kinds: [1], // Text notes
+  authors: ['your-pubkey'], // Suas notas
+})
+```
 
-### DM policies
+### Obter Perfil
 
-- **pairing** (default): unknown senders get a pairing code.
-- **allowlist**: only pubkeys in `allowFrom` can DM.
-- **open**: public inbound DMs (requires `allowFrom: ["*"]`).
-- **disabled**: ignore inbound DMs.
+```typescript
+const profile = await channel.getProfile()
+console.log(profile)
+// { name: 'Pool Bot', about: 'AI Bot...', picture: '...' }
+```
 
-### Allowlist example
+## Config Options
 
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "dmPolicy": "allowlist",
-      "allowFrom": ["npub1abc...", "npub1xyz..."]
-    }
-  }
+```typescript
+type NostrConfig = {
+  relays: string[]          // Lista de relays
+  privateKey?: string       // Private key (hex) - opcional
+  publicKey?: string        // Public key (hex)
+  subscribeFilter?: Filter  // Filtro de subscription
 }
 ```
 
-## Key formats
+## Kinds Suportados
 
-Accepted formats:
+| Kind | Tipo           | Descrição              |
+|------|----------------|------------------------|
+| 0    | Metadata       | Perfil do usuário      |
+| 1    | Text Note      | Nota de texto          |
+| 4    | Encrypted DM   | Mensagem direta (NIP-04) |
+| 7    | Reaction       | Reação (like)          |
 
-- **Private key:** `nsec...` or 64-char hex
-- **Pubkeys (`allowFrom`):** `npub...` or hex
+## Relays Recomendados
 
-## Relays
+### Principais
 
-Defaults: `relay.damus.io` and `nos.lol`.
+```
+wss://relay.damus.io       - Damus relay
+wss://nos.lol              - Nos.lol relay
+wss://relay.nostr.band      - Nostr Band
+wss://relay.snort.social    - Snort
+wss://purplepag.es          - Purple Pages
+```
+
+### Brasileiros
+
+```
+wss://relay.nostr.com.br    - Nostr Brasil
+```
+
+### Especializados
+
+```
+wss://filter.nostr.wine     - Filtros avançados
+wss://cache.primal.net      - Cache/History
+```
+
+## Exemplos
+
+### Bot de Resposta Automática
 
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "relays": [
-        "wss://relay.damus.io",
-        "wss://relay.primal.net",
-        "wss://nostr.wine"
-      ]
-    }
+```typescript
+await channel.receiveMessages((msg) => {
+  if (msg.text.includes('!hello')) {
+    channel.sendMessage({
+      text: `Hello ${msg.from}!`,
+    })
   }
-}
+})
+```
+
+### Bridge Nostr <-> Telegram
+
+```typescript
+// Nostr -> Telegram
+await channel.receiveMessages((msg) => {
+  telegramChannel.sendMessage({
+    text: `[Nostr] ${msg.from}: ${msg.text}`,
+  })
+})
+
+// Telegram -> Nostr
+telegramChannel.receiveMessages((msg) => {
+  channel.sendMessage({
+    text: `[Telegram] ${msg.from}: ${msg.text}`,
+  })
+})
 ```
 
-Tips:
+### Publicar Agenda Diária
 
-- Use 2-3 relays for redundancy.
-- Avoid too many relays (latency, duplication).
-- Paid relays can improve reliability.
-- Local relays are fine for testing (`ws://localhost:7777`).
+```typescript
+cron.schedule('0 8 * * *', async () => {
+  await channel.sendMessage({
+    text: 'Bom dia! Agenda de hoje:\n- Meeting 10h\n- Deploy 15h',
+  })
+})
+```
 
-## Protocol support
+## NIPs Suportados
 
-| NIP | Status | Description |
-| --- | --- | --- |
-| NIP-01 | Supported | Basic event format + profile metadata |
-| NIP-04 | Supported | Encrypted DMs (`kind:4`) |
-| NIP-17 | Planned | Gift-wrapped DMs |
-| NIP-44 | Planned | Versioned encryption |
+### NIP-01: Basic Protocol
+- ✅ Publicar eventos
+- ✅ Subscribe a eventos
+- ✅ Múltiplos relays
 
-## Testing
+### NIP-04: Encrypted Direct Message
+- ✅ Enviar DMs criptografadas
+- ✅ Receber DMs criptografadas
 
-### Local relay
+### NIP-05: DNS-based Verification
+- ⏳ Verificação por DNS (future)
+
+### NIP-19: bech32-encoded Entities
+- ✅ Suporte a npub/nsec format
+
+## Security
+
+### Gerenciamento de Chaves
 
 ```bash
-# Start strfry
-docker run -p 7777:7777 ghcr.io/hoytech/strfry
-```
+# Nunca compartilhe sua private key!
+# Armazene em local seguro
 
-```json
-{
-  "channels": {
-    "nostr": {
-      "privateKey": "${NOSTR_PRIVATE_KEY}",
-      "relays": ["ws://localhost:7777"]
-    }
-  }
-}
+# Usar variável de ambiente
+export NOSTR_PRIVATE_KEY="your-key"
+
+# Ou arquivo seguro
+poolbot config set channels.nostr.privateKey --secure
 ```
 
-### Manual test
+### Best Practices
 
-1) Note the bot pubkey (npub) from logs.
-2) Open a Nostr client (Damus, Amethyst, etc.).
-3) DM the bot pubkey.
-4) Verify the response.
+1. **Nunca commit keys** no git
+2. **Use env vars** para produção
+3. **Rotação de chaves** periódica
+4. **Múltiplos relays** para redundância
+5. **Valide eventos** recebidos
 
 ## Troubleshooting
 
-### Not receiving messages
+### Erro de Conexão
 
-- Verify the private key is valid.
-- Ensure relay URLs are reachable and use `wss://` (or `ws://` for local).
-- Confirm `enabled` is not `false`.
-- Check Gateway logs for relay connection errors.
+```
+Error: Nostr connection failed
+```
 
-### Not sending responses
+**Solução:**
+- Verificar URLs dos relays
+- Testar com wscat: `wscat -c wss://relay.damus.io`
+- Verificar firewall
 
-- Check relay accepts writes.
-- Verify outbound connectivity.
-- Watch for relay rate limits.
+### Não consegue publicar
+
+```
+Failed to publish to any relay
+```
 
-### Duplicate responses
+**Solução:**
+- Verificar se private key está configurada
+- Testar relay individualmente
+- Verificar rate limits do relay
 
-- Expected when using multiple relays.
-- Messages are deduplicated by event ID; only the first delivery triggers a response.
+### DMs não funcionam
 
-## Security
+```
+Cannot send DM without private key
+```
+
+**Solução:**
+- Configurar privateKey no config
+- Verificar formato hex da chave
+- Verificar pubkey do recipient
+
+## Comandos CLI
+
+```bash
+# Gerar chaves
+poolbot nostr generate-keys
+
+# Publicar nota
+poolbot nostr publish "Hello world!"
+
+# Ver perfil
+poolbot nostr profile
+
+# Listar relays
+poolbot nostr relays
+
+# Testar conexão
+poolbot nostr test
+```
+
+## API Reference
+
+### Methods
+
+- `connect()` - Conectar aos relays
+- `disconnect()` - Desconectar
+- `publishEvent(event)` - Publicar evento
+- `sendMessage(message)` - Publicar nota (Kind 1)
+- `sendDirectMessage(pubkey, message)` - DM (Kind 4)
+- `subscribe(filter)` - Inscrever em eventos
+- `receiveMessages(callback)` - Configurar receiver
+- `getPresences()` - Obter presenças
+- `getProfile()` - Obter perfil
+- `getPublicKey()` - Obter pubkey
+
+### Events
+
+- `connect` - Conectado aos relays
+- `disconnect` - Desconectado
+- `message` - Nova mensagem recebida
+- `error` - Erro
+
+## Arquivos Relacionados
 
-- Never commit private keys.
-- Use environment variables for keys.
-- Consider `allowlist` for production bots.
+- `extensions/nostr/src/nostr-channel.ts` - Implementação
+- `extensions/nostr/src/index.ts` - Entry point
+- `extensions/nostr/package.json` - Dependências (nostr-tools)
 
-## Limitations (MVP)
+## Links Relacionados
 
-- Direct messages only (no group chats).
-- No media attachments.
-- NIP-04 only (NIP-17 gift-wrap planned).
+- [Nostr Protocol](https://github.com/nostr-protocol/nostr)
+- [NIPs](https://github.com/nostr-protocol/nips)
+- [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
+- [Damus](https://damus.io/)

package/docs/components/command-palette.md

@@ -0,0 +1,166 @@
+# Command Palette
+
+A Command Palette é uma interface de navegação rápida acessível via `Cmd+K` (Mac) ou `Ctrl+K` (Windows/Linux) que permite navegar e executar ações rapidamente no dashboard do Pool Bot.
+
+## Features
+
+- 🔍 **Busca Fuzzy** - Encontre comandos e navegação rapidamente
+- ⌨️ **Atalhos de Teclado** - Navegação completa sem mouse
+- 📂 **Categorização** - Itens organizados por categoria
+- 🚀 **Acesso Rápido** - Execute ações sem navegar por menus
+
+## Categorias
+
+### Navigation
+Acesso rápido às principais seções:
+- **Overview** - Visão geral do sistema
+- **Sessions** - Gerenciamento de sessões
+- **Scheduled** - Jobs agendados (Cron)
+- **Skills** - Habilidades e comandos
+- **Settings** - Configurações
+- **Agents** - Gerenciamento de agentes
+- **Nodes** - Nós de processamento *(Novo)*
+- **Exec Approvals** - Aprovações pendentes *(Novo)*
+- **Pair Device** - Pairing de dispositivos *(Novo)*
+- **Usage** - Analytics de uso *(Novo)*
+- **Logs** - Logs do sistema *(Novo)*
+- **Debug** - Ferramentas de debug *(Novo)*
+
+### Search
+Comandos slash disponíveis:
+- `/fast` - Toggle fast mode
+- `/btw` - By the way (contexto)
+- `/verbose` - Modo verboso
+- `/stop` - Parar sessão
+- `/model` - Mudar modelo
+- `/skill` - Executar skill
+- `/export` - Exportar chat
+- `/focus` - Focus mode
+
+### Skills
+Atalhos para skills frequentes:
+- **Shell Command** - Executar comando shell
+- **Debug Mode** - Toggle debug
+- **Focus Mode** - Toggle focus
+- **Export Chat** - Exportar conversa
+
+## Uso
+
+### Abrir Command Palette
+
+```
+Mac: Cmd+K
+Windows/Linux: Ctrl+K
+```
+
+### Navegar
+
+```
+↓ / Tab      - Próximo item
+↑ / Shift+Tab - Item anterior
+Enter        - Selecionar item
+Esc          - Fechar
+```
+
+### Buscar
+
+Digite para filtrar itens:
+- `nodes` - Filtra por "Nodes"
+- `setti` - Filtra por "Settings"
+- `/exp` - Filtra comandos slash começando com /exp
+
+## Exemplo de Uso
+
+1. Pressione `Cmd+K`
+2. Digite `nodes`
+3. Pressione `Enter` para navegar para Nodes Management
+
+## API
+
+### Programmatic Usage
+
+```typescript
+import { getPaletteItems, filteredItems } from './command-palette'
+
+// Obter todos os itens
+const allItems = getPaletteItems()
+
+// Filtrar itens
+const filtered = filteredItems('nodes')
+
+// Navegar programaticamente
+props.onNavigate('nodes')
+```
+
+### Props do Componente
+
+```typescript
+type CommandPaletteProps = {
+  open: boolean                    // Palette aberta?
+  query: string                    // Texto da busca
+  activeIndex: number              // Índice do item ativo
+  onToggle: () => void             // Toggle open/close
+  onQueryChange: (q: string) => void // Mudar busca
+  onActiveIndexChange: (i: number) => void // Mudar índice
+  onNavigate: (tab: string) => void // Navegar
+  onSlashCommand: (cmd: string) => void // Executar comando
+}
+```
+
+## Customização
+
+### Adicionar Novos Itens
+
+Edite `ui/src/ui/views/command-palette.ts`:
+
+```typescript
+const PALETTE_ITEMS: PaletteItem[] = [
+  // ... itens existentes
+  {
+    id: "nav-custom",
+    label: "Custom Page",
+    icon: "star",
+    category: "navigation",
+    action: "nav:custom",
+    description: "Custom navigation",
+  },
+];
+```
+
+### Adicionar Skills
+
+```typescript
+{
+  id: "skill-custom",
+  label: "Custom Skill",
+  icon: "zap",
+  category: "skills",
+  action: "/skill custom",
+  description: "Run custom skill",
+}
+```
+
+## Testes
+
+```bash
+# Rodar testes
+pnpm test -- command-palette.test.ts
+
+# Testes incluem:
+# - Filtragem de itens
+# - Navegação por categoria
+# - Busca por descrição
+# - Atalhos de teclado
+```
+
+## Arquivos Relacionados
+
+- `ui/src/ui/views/command-palette.ts` - Componente principal
+- `ui/src/ui/views/command-palette.test.ts` - Testes unitários
+- `ui/src/ui/chat/slash-commands.ts` - Comandos slash
+
+## Links Relacionados
+
+- [Dashboard](/components/dashboard)
+- [Navegação](/guides/navigation)
+- [Atalhos de Teclado](/guides/keyboard-shortcuts)