@poolzin/pool-bot 2026.3.21 → 2026.3.23

package/docs/channels/googlechat.md

@@ -1,220 +1,249 @@
----
-summary: "Google Chat app support status, capabilities, and configuration"
-read_when:
-  - Working on Google Chat channel features
----
-# Google Chat (Chat API)
-
-Status: ready for DMs + spaces via Google Chat API webhooks (HTTP only).
-
-## Quick setup (beginner)
-1) Create a Google Cloud project and enable the **Google Chat API**.
-   - Go to: [Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
-   - Enable the API if it is not already enabled.
-2) Create a **Service Account**:
-   - Press **Create Credentials** > **Service Account**.
-   - Name it whatever you want (e.g., `poolbot-chat`).
-   - Leave permissions blank (press **Continue**).
-   - Leave principals with access blank (press **Done**).
-3) Create and download the **JSON Key**:
-   - In the list of service accounts, click on the one you just created.
-   - Go to the **Keys** tab.
-   - Click **Add Key** > **Create new key**.
-   - Select **JSON** and press **Create**.
-4) Store the downloaded JSON file on your gateway host (e.g., `~/.poolbot/googlechat-service-account.json`).
-5) Create a Google Chat app in the [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat):
-   - Fill in the **Application info**:
-     - **App name**: (e.g. `Pool Bot`)
-     - **Avatar URL**: (e.g. `https://molt.bot/logo.png`)
-     - **Description**: (e.g. `Personal AI Assistant`)
-   - Enable **Interactive features**.
-   - Under **Functionality**, check **Join spaces and group conversations**.
-   - Under **Connection settings**, select **HTTP endpoint URL**.
-   - Under **Triggers**, select **Use a common HTTP endpoint URL for all triggers** and set it to your gateway's public URL followed by `/googlechat`.
-     - *Tip: Run `poolbot status` to find your gateway's public URL.*
-   - Under **Visibility**, check **Make this Chat app available to specific people and groups in <Your Domain>**.
-   - Enter your email address (e.g. `user@example.com`) in the text box.
-   - Click **Save** at the bottom.
-6) **Enable the app status**:
-   - After saving, **refresh the page**.
-   - Look for the **App status** section (usually near the top or bottom after saving).
-   - Change the status to **Live - available to users**.
-   - Click **Save** again.
-7) Configure Pool Bot with the service account path + webhook audience:
-   - Env: `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
-   - Or config: `channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`.
-8) Set the webhook audience type + value (matches your Chat app config).
-9) Start the gateway. Google Chat will POST to your webhook path.
-
-## Add to Google Chat
-Once the gateway is running and your email is added to the visibility list:
-1) Go to [Google Chat](https://chat.google.com/).
-2) Click the **+** (plus) icon next to **Direct Messages**.
-3) In the search bar (where you usually add people), type the **App name** you configured in the Google Cloud Console.
-   - **Note**: The bot will *not* appear in the "Marketplace" browse list because it is a private app. You must search for it by name.
-4) Select your bot from the results.
-5) Click **Add** or **Chat** to start a 1:1 conversation.
-6) Send "Hello" to trigger the assistant!
-
-## Public URL (Webhook-only)
-Google Chat webhooks require a public HTTPS endpoint. For security, **only expose the `/googlechat` path** to the internet. Keep the Pool Bot dashboard and other sensitive endpoints on your private network.
-
-### Option A: Tailscale Funnel (Recommended)
-Use Tailscale Serve for the private dashboard and Funnel for the public webhook path. This keeps `/` private while exposing only `/googlechat`.
-
-1. **Check what address your gateway is bound to:**
-   ```bash
-   ss -tlnp | grep 18789
-   ```
-   Note the IP address (e.g., `127.0.0.1`, `0.0.0.0`, or your Tailscale IP like `100.x.x.x`).
-
-2. **Expose the dashboard to the tailnet only (port 8443):**
-   ```bash
-   # If bound to localhost (127.0.0.1 or 0.0.0.0):
-   tailscale serve --bg --https 8443 http://127.0.0.1:18789
-
-   # If bound to Tailscale IP only (e.g., 100.106.161.80):
-   tailscale serve --bg --https 8443 http://100.106.161.80:18789
-   ```
-
-3. **Expose only the webhook path publicly:**
-   ```bash
-   # If bound to localhost (127.0.0.1 or 0.0.0.0):
-   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
-
-   # If bound to Tailscale IP only (e.g., 100.106.161.80):
-   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
-   ```
-
-4. **Authorize the node for Funnel access:**
-   If prompted, visit the authorization URL shown in the output to enable Funnel for this node in your tailnet policy.
-
-5. **Verify the configuration:**
-   ```bash
-   tailscale serve status
-   tailscale funnel status
-   ```
-
-Your public webhook URL will be:
-`https://<node-name>.<tailnet>.ts.net/googlechat`
-
-Your private dashboard stays tailnet-only:
-`https://<node-name>.<tailnet>.ts.net:8443/`
-
-Use the public URL (without `:8443`) in the Google Chat app config.
-
-> Note: This configuration persists across reboots. To remove it later, run `tailscale funnel reset` and `tailscale serve reset`.
-
-### Option B: Reverse Proxy (Caddy)
-If you use a reverse proxy like Caddy, only proxy the specific path:
-```caddy
-your-domain.com {
-    reverse_proxy /googlechat* localhost:18789
-}
+# Google Chat Channel
+
+Integração com Google Chat para envio e recebimento de mensagens em spaces do Google Workspace.
+
+## Features
+
+- ✅ **OAuth 2.0** - Autenticação segura com service accounts
+- 💬 **Spaces** - Suporte a spaces do Google Chat
+- 🧵 **Threads** - Respostas em threads
+- 🔔 **Webhooks** - Recebimento via webhooks
+- 👥 **Presence** - Tracking básico de presença
+
+## Configuração
+
+### 1. Criar Service Account
+
+1. Acesse [Google Cloud Console](https://console.cloud.google.com)
+2. Crie um novo projeto ou selecione existente
+3. Ative a **Google Chat API**
+4. Vá para **APIs & Services** > **Credentials**
+5. Clique **Create Credentials** > **Service Account**
+6. Preencha informações e clique **Create**
+7. Na service account, vá para **Keys** > **Add Key** > **Create new key**
+8. Selecione **JSON** e baixe o arquivo
+
+### 2. Configurar Pool Bot
+
+```bash
+# Copiar conteúdo do JSON para config
+poolbot config set channels.googlechat.credentials '{"client_email":"...","private_key":"..."}'
+
+# Ou editar config manualmente
+# ~/.poolbot/config.json
+```
+
+### 3. Configurar Space
+
+```bash
+# ID do space (opcional)
+poolbot config set channels.googlechat.spaceId YOUR_SPACE_ID
+
+# Habilitar canal
+poolbot config set channels.googlechat.enabled true
 ```
-With this config, any request to `your-domain.com/` will be ignored or returned as 404, while `your-domain.com/googlechat` is safely routed to Pool Bot.
-
-### Option C: Cloudflare Tunnel
-Configure your tunnel's ingress rules to only route the webhook path:
-- **Path**: `/googlechat` -> `http://localhost:18789/googlechat`
-- **Default Rule**: HTTP 404 (Not Found)
-
-## How it works
-
-1. Google Chat sends webhook POSTs to the gateway. Each request includes an `Authorization: Bearer <token>` header.
-2. Pool Bot verifies the token against the configured `audienceType` + `audience`:
-   - `audienceType: "app-url"` → audience is your HTTPS webhook URL.
-   - `audienceType: "project-number"` → audience is the Cloud project number.
-3. Messages are routed by space:
-   - DMs use session key `agent:<agentId>:googlechat:dm:<spaceId>`.
-   - Spaces use session key `agent:<agentId>:googlechat:group:<spaceId>`.
-4. DM access is pairing by default. Unknown senders receive a pairing code; approve with:
-   - `poolbot pairing approve googlechat <code>`
-5. Group spaces require @-mention by default. Use `botUser` if mention detection needs the app’s user name.
-
-## Targets
-Use these identifiers for delivery and allowlists:
-- Direct messages: `users/<userId>` or `users/<email>` (email addresses are accepted).
-- Spaces: `spaces/<spaceId>`.
-
-## Config highlights
-```json5
-{
-  channels: {
-    "googlechat": {
-      enabled: true,
-      serviceAccountFile: "/path/to/service-account.json",
-      audienceType: "app-url",
-      audience: "https://gateway.example.com/googlechat",
-      webhookPath: "/googlechat",
-      botUser: "users/1234567890", // optional; helps mention detection
-      dm: {
-        policy: "pairing",
-        allowFrom: ["users/1234567890", "name@example.com"]
-      },
-      groupPolicy: "allowlist",
-      groups: {
-        "spaces/AAAA": {
-          allow: true,
-          requireMention: true,
-          users: ["users/1234567890"],
-          systemPrompt: "Short answers only."
-        }
-      },
-      actions: { reactions: true },
-      typingIndicator: "message",
-      mediaMaxMb: 20
-    }
+
+### 4. Adicionar Bot ao Space
+
+1. No Google Chat, vá para o space
+2. Clique no nome do space > **Apps**
+3. Adicione seu bot
+
+## Uso
+
+### Enviar Mensagem
+
+```typescript
+import { createGoogleChatChannel } from '@poolbot/googlechat'
+
+const channel = createGoogleChatChannel({
+  credentials: {
+    client_email: 'bot@project.iam.gserviceaccount.com',
+    private_key: '-----BEGIN PRIVATE KEY-----\n...',
+  },
+  spaceId: 'spaces/AAA...',
+})
+
+await channel.connect()
+
+await channel.sendMessage({
+  id: 'msg-1',
+  text: 'Hello from Pool Bot!',
+  threadId: 'thread-123', // Opcional
+})
+```
+
+### Receber Mensagens
+
+```typescript
+// Configurar webhook no Google Chat
+// Settings > Bots > Your Bot > Configure webhooks
+
+// No seu servidor webhook:
+app.post('/webhook/googlechat', async (req, res) => {
+  const message = req.body
+  
+  await channel.receiveMessages((msg) => {
+    console.log('Received:', msg)
+  })
+})
+```
+
+### Threads
+
+```typescript
+// Enviar em thread existente
+await channel.sendMessage({
+  text: 'Reply in thread',
+  threadId: 'thread-123',
+})
+
+// Obter mensagens de thread
+const messages = await channel.getThreadMessages('thread-123')
+```
+
+## Config Options
+
+```typescript
+type GoogleChatConfig = {
+  credentials: {
+    client_email: string    // Service account email
+    private_key: string     // Private key (PEM format)
   }
+  spaceId?: string          // Space ID (opcional)
+  threadKey?: string        // Thread key para threading
 }
 ```
 
-Notes:
-- Service account credentials can also be passed inline with `serviceAccount` (JSON string).
-- Default webhook path is `/googlechat` if `webhookPath` isn’t set.
-- Reactions are available via the `reactions` tool and `channels action` when `actions.reactions` is enabled.
-- `typingIndicator` supports `none`, `message` (default), and `reaction` (reaction requires user OAuth).
-- Attachments are downloaded through the Chat API and stored in the media pipeline (size capped by `mediaMaxMb`).
+## Webhook Setup
+
+### 1. Criar Webhook
+
+No Google Chat:
+1. Vá para **Configure bots**
+2. Selecione seu bot
+3. Em **Incoming webhooks**, clique **Add webhook**
+4. Dê um nome e salve a URL
+
+### 2. Configurar no Pool Bot
+
+```bash
+poolbot config set channels.googlechat.webhookUrl YOUR_WEBHOOK_URL
+```
+
+### 3. Handler
+
+```typescript
+// Exemplo com Express
+app.post('/googlechat', (req, res) => {
+  const { text, user, space } = req.body
+  
+  // Processar mensagem
+  handleMessage({
+    from: user.displayName,
+    text: text,
+    space: space.name,
+  })
+  
+  res.sendStatus(200)
+})
+```
+
+## Limitações
+
+- ❌ Sem suporte a mensagens diretas (apenas spaces)
+- ❌ Presence tracking limitado
+- ⚠️ Webhooks requerem servidor público
+- ⚠️ Service account necessária
 
 ## Troubleshooting
 
-### 405 Method Not Allowed
-If Google Cloud Logs Explorer shows errors like:
+### Erro de Autenticação
+
 ```
-status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
+Error: Google Chat connection failed: invalid_grant
 ```
 
-This means the webhook handler isn't registered. Common causes:
-1. **Channel not configured**: The `channels.googlechat` section is missing from your config. Verify with:
-   ```bash
-   poolbot config get channels.googlechat
-   ```
-   If it returns "Config path not found", add the configuration (see [Config highlights](#config-highlights)).
-
-2. **Plugin not enabled**: Check plugin status:
-   ```bash
-   poolbot plugins list | grep googlechat
-   ```
-   If it shows "disabled", add `plugins.entries.googlechat.enabled: true` to your config.
-
-3. **Gateway not restarted**: After adding config, restart the gateway:
-   ```bash
-   poolbot gateway restart
-   ```
-
-Verify the channel is running:
-```bash
-poolbot channels status
-# Should show: Google Chat default: enabled, configured, ...
+**Solução:**
+- Verificar se service account está ativa
+- Regenerar chave JSON
+- Verificar permissões da API
+
+### Space não encontrado
+
+```
+Error: Space not found: spaces/XXX
+```
+
+**Solução:**
+- Verificar space ID
+- Adicionar bot ao space
+- Verificar permissões
+
+### Webhook não funciona
+
+**Solução:**
+- Verificar URL do webhook
+- Configurar firewall/SSL
+- Testar com curl:
+  ```bash
+  curl -X POST YOUR_WEBHOOK_URL \
+    -H "Content-Type: application/json" \
+    -d '{"text":"test"}'
+  ```
+
+## Exemplos
+
+### Notificação Automática
+
+```typescript
+// Enviar notificação diária
+cron.schedule('0 9 * * *', async () => {
+  await channel.sendMessage({
+    text: 'Bom dia! Aqui está o resumo de hoje...',
+  })
+})
+```
+
+### Resposta Automática
+
+```typescript
+await channel.receiveMessages((msg) => {
+  if (msg.text.includes('preço')) {
+    channel.sendMessage({
+      text: 'Nossos planos começam em R$ 99/mês',
+      threadId: msg.threadId,
+    })
+  }
+})
 ```
 
-### Other issues
-- Check `poolbot channels status --probe` for auth errors or missing audience config.
-- If no messages arrive, confirm the Chat app's webhook URL + event subscriptions.
-- If mention gating blocks replies, set `botUser` to the app's user resource name and verify `requireMention`.
-- Use `poolbot logs --follow` while sending a test message to see if requests reach the gateway.
+## API Reference
+
+### Methods
+
+- `connect()` - Conectar ao Google Chat
+- `disconnect()` - Desconectar
+- `sendMessage(message)` - Enviar mensagem
+- `receiveMessages(callback)` - Configurar receiver
+- `getThreadMessages(threadId)` - Obter thread
+- `getPresences()` - Obter presenças (limitado)
+
+### Events
+
+- `message` - Nova mensagem recebida
+- `connect` - Conexão estabelecida
+- `disconnect` - Desconectado
+- `error` - Erro na conexão
+
+## Arquivos Relacionados
+
+- `extensions/googlechat/src/googlechat-channel.ts` - Implementação
+- `extensions/googlechat/src/index.ts` - Entry point
+- `extensions/googlechat/package.json` - Dependências
+
+## Links Relacionados
 
-Related docs:
-- [Gateway configuration](/gateway/configuration)
-- [Security](/gateway/security)
-- [Reactions](/tools/reactions)
+- [Google Chat API Docs](https://developers.google.com/chat)
+- [Service Accounts](https://cloud.google.com/iam/docs/service-accounts)
+- [Webhooks Guide](https://developers.google.com/chat/api/guides/v1/webhooks)