chat 4.13.1 → 4.13.3

package/docs/adapters/gchat.mdx

@@ -0,0 +1,232 @@
+---
+title: Google Chat
+description: Configure the Google Chat adapter with service account authentication and optional Pub/Sub.
+type: integration
+prerequisites:
+  - /docs/getting-started
+---
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/gchat
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createGoogleChatAdapter } from "@chat-adapter/gchat";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    gchat: createGoogleChatAdapter({
+      credentials: JSON.parse(process.env.GOOGLE_CHAT_CREDENTIALS!),
+    }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Google Chat!");
+});
+```
+
+## Google Chat setup
+
+### 1. Create a GCP project
+
+1. Go to [console.cloud.google.com](https://console.cloud.google.com)
+2. Click the project dropdown then **New Project**
+3. Enter project name and click **Create**
+
+### 2. Enable required APIs
+
+Go to **APIs & Services** then **Library** and enable:
+
+- **Google Chat API**
+- **Google Workspace Events API** (for receiving all messages)
+- **Cloud Pub/Sub API** (for receiving all messages)
+
+### 3. Create a service account
+
+1. Go to **IAM & Admin** then **Service Accounts**
+2. Click **Create Service Account**
+3. Enter name and description
+4. Click **Create and Continue**
+5. Skip the optional steps, click **Done**
+
+### 4. Create service account key
+
+1. Click on your service account
+2. Go to **Keys** tab
+3. Click **Add Key** then **Create new key**
+4. Select **JSON** and click **Create**
+5. Copy the entire JSON content as `GOOGLE_CHAT_CREDENTIALS`
+
+<Callout type="info">
+If your organization has the `iam.disableServiceAccountKeyCreation` constraint enabled, you need to relax it or add an exception for your project in **IAM & Admin** then **Organization Policies**.
+</Callout>
+
+### 5. Configure Google Chat app
+
+1. Go to the [Chat API configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
+2. Click **Configuration** and fill in:
+   - **App name**: Your bot's display name
+   - **Avatar URL**: URL to your bot's avatar
+   - **Description**: What your bot does
+   - **Interactive features**: Enable **Receive 1:1 messages** and **Join spaces and group conversations**
+   - **Connection settings**: Select **App URL**
+   - **App URL**: `https://your-domain.com/api/webhooks/gchat`
+   - **Visibility**: Choose who can discover your app
+3. Click **Save**
+
+### 6. Add bot to a space
+
+1. Open Google Chat
+2. Create or open a Space
+3. Click the space name then **Manage apps & integrations**
+4. Click **Add apps**, search for your app, and click **Add**
+
+## Pub/Sub for all messages (optional)
+
+By default, Google Chat only sends webhooks for @mentions. To receive all messages in a space, set up Workspace Events with Pub/Sub.
+
+```typescript title="lib/bot.ts" lineNumbers
+createGoogleChatAdapter({
+  credentials: JSON.parse(process.env.GOOGLE_CHAT_CREDENTIALS!),
+  pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
+  impersonateUser: process.env.GOOGLE_CHAT_IMPERSONATE_USER,
+});
+```
+
+### 1. Create Pub/Sub topic
+
+1. Go to **Pub/Sub** then **Topics**
+2. Click **Create Topic**
+3. Enter topic ID (e.g., `chat-events`)
+4. Uncheck **Add a default subscription**
+5. Click **Create**
+6. Copy the full topic name as `GOOGLE_CHAT_PUBSUB_TOPIC` (format: `projects/your-project-id/topics/chat-events`)
+
+### 2. Grant Chat service account access
+
+1. Go to your Pub/Sub topic
+2. Click **Permissions** tab
+3. Click **Add Principal**
+4. Enter `chat-api-push@system.gserviceaccount.com`
+5. Select role **Pub/Sub Publisher**
+6. Click **Save**
+
+### 3. Create push subscription
+
+1. Go to **Pub/Sub** then **Subscriptions**
+2. Click **Create Subscription**
+3. Select your topic
+4. Set **Delivery type** to Push
+5. Set **Endpoint URL** to `https://your-domain.com/api/webhooks/gchat`
+6. Click **Create**
+
+### 4. Enable domain-wide delegation
+
+Domain-wide delegation is required for creating Workspace Events subscriptions and initiating DMs.
+
+**Step 1 — Enable delegation on the service account:**
+
+1. Go to **IAM & Admin** then **Service Accounts**
+2. Click on your service account
+3. Check **Enable Google Workspace Domain-wide Delegation** and save
+4. Copy the **Client ID** (a numeric ID, not the email)
+
+**Step 2 — Authorize in Google Admin Console:**
+
+1. Go to [Google Admin Console](https://admin.google.com)
+2. Go to **Security** then **Access and data control** then **API controls**
+3. Click **Manage Domain Wide Delegation** then **Add new**
+4. Enter the numeric **Client ID** from Step 1
+5. Add OAuth scopes (comma-separated, on one line):
+   ```
+   https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.spaces.create
+   ```
+6. Click **Authorize**
+
+**Step 3 — Set environment variable:**
+
+Set `GOOGLE_CHAT_IMPERSONATE_USER` to an admin user email in your domain (e.g., `admin@yourdomain.com`).
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `credentials` | Yes* | Service account credentials JSON |
+| `useADC` | No | Use Application Default Credentials instead |
+| `pubsubTopic` | No | Pub/Sub topic for Workspace Events |
+| `impersonateUser` | No | User email for domain-wide delegation |
+
+*Either `credentials` or `useADC: true` is required.
+
+## Environment variables
+
+```bash title=".env.local"
+GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}
+
+# Optional: for receiving all messages
+GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-events
+GOOGLE_CHAT_IMPERSONATE_USER=admin@yourdomain.com
+```
+
+## Features
+
+| Feature | Supported |
+|---------|-----------|
+| Mentions | Yes |
+| Reactions (add/remove) | Yes (via Workspace Events) |
+| Cards (Google Chat Cards) | Yes |
+| Modals | No |
+| Streaming | Post+Edit fallback |
+| DMs | Yes (requires delegation) |
+| Ephemeral messages | Yes (native) |
+| File uploads | Yes |
+| Typing indicator | No |
+| Message history | Yes |
+
+## Limitations
+
+- **Typing indicators**: Not supported by Google Chat API. `startTyping()` is a no-op.
+- **Adding reactions**: The Google Chat API doesn't support service account (app) authentication for adding reactions. To use `addReaction()` or `removeReaction()`, you need domain-wide delegation with `impersonateUser` configured — but the reaction appears as coming from the impersonated user, not the bot.
+
+### Message history (`fetchMessages`)
+
+Fetching message history requires domain-wide delegation with the `impersonateUser` config option set. The impersonated user must have access to the spaces you want to read from. See the [Pub/Sub setup](#4-enable-domain-wide-delegation) above for configuring delegation and OAuth scopes.
+
+## Troubleshooting
+
+### No webhook received
+
+- Verify the App URL is correct in Google Chat configuration
+- Check that the Chat API is enabled
+- Ensure the service account has the necessary permissions
+
+### Pub/Sub not working
+
+- Verify `chat-api-push@system.gserviceaccount.com` has Pub/Sub Publisher role
+- Check that the push subscription URL is correct
+- Verify domain-wide delegation is configured with correct scopes
+- Check `GOOGLE_CHAT_IMPERSONATE_USER` is a valid admin email
+
+### "Permission denied" for Workspace Events
+
+- Ensure domain-wide delegation is configured
+- Verify the OAuth scopes are exactly as specified
+- Check that the impersonated user has access to the spaces
+
+### "Insufficient Permission" for DMs
+
+- DMs require domain-wide delegation with `chat.spaces` and `chat.spaces.create` scopes
+- Scope changes can take up to 24 hours to propagate
+
+### Button clicks not received
+
+- Verify **Interactive features** is enabled in the Google Chat app configuration
+- Check that the App URL is correctly set and accessible
+- Button clicks go to the same webhook URL as messages

package/docs/adapters/github.mdx

@@ -0,0 +1,225 @@
+---
+title: GitHub
+description: Configure the GitHub adapter to respond to @mentions in PR and issue comment threads.
+type: integration
+prerequisites:
+  - /docs/getting-started
+---
+
+The GitHub adapter treats issue and pull request comments as messages, and issues/PRs as threads.
+
+## Installation
+
+```sh title="Terminal"
+pnpm add @chat-adapter/github
+```
+
+## Usage
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createGitHubAdapter } from "@chat-adapter/github";
+
+const bot = new Chat({
+  userName: "my-bot",
+  adapters: {
+    github: createGitHubAdapter({
+      token: process.env.GITHUB_TOKEN!,
+      webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+      userName: "my-bot",
+    }),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from GitHub!");
+});
+```
+
+## Authentication
+
+### Option A: Personal Access Token
+
+Best for personal projects, testing, or single-repo bots.
+
+1. Go to [Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
+2. Create a new token with `repo` scope
+3. Set `GITHUB_TOKEN` environment variable
+
+```typescript title="lib/bot.ts" lineNumbers
+createGitHubAdapter({
+  token: process.env.GITHUB_TOKEN!,
+  webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+  userName: "my-bot",
+});
+```
+
+### Option B: GitHub App (recommended)
+
+Better rate limits, security, and supports multiple installations.
+
+**1. Create the app:**
+
+1. Go to [Settings > Developer settings > GitHub Apps > New GitHub App](https://github.com/settings/apps/new)
+2. Set **Webhook URL** to `https://your-domain.com/api/webhooks/github`
+3. Generate and set a **Webhook secret**
+4. Set permissions:
+   - Repository > Issues: Read & write
+   - Repository > Pull requests: Read & write
+   - Repository > Metadata: Read-only
+5. Subscribe to events: Issue comment, Pull request review comment
+6. Click **Create GitHub App**
+7. Note the **App ID** and click **Generate a private key**
+
+**2. Install the app:**
+
+1. Go to your app's settings then **Install App**
+2. Click **Install** and choose repositories
+3. Note the **Installation ID** from the URL:
+   ```
+   https://github.com/settings/installations/12345678
+                                              ^^^^^^^^
+   ```
+
+**Single-tenant:**
+
+```typescript title="lib/bot.ts" lineNumbers
+createGitHubAdapter({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!),
+  webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+  userName: "my-bot[bot]",
+});
+```
+
+**Multi-tenant (omit `installationId`):**
+
+```typescript title="lib/bot.ts" lineNumbers
+createGitHubAdapter({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+  userName: "my-bot[bot]",
+});
+```
+
+The adapter automatically extracts installation IDs from webhooks and caches API clients per-installation.
+
+## Webhook setup
+
+For repository or organization webhooks:
+
+1. Go to repository/org **Settings** then **Webhooks** then **Add webhook**
+2. Set **Payload URL** to `https://your-domain.com/api/webhooks/github`
+3. Set **Content type** to `application/json` (required — the default `application/x-www-form-urlencoded` does not work)
+4. Set **Secret** to match your `webhookSecret`
+5. Select events: Issue comments, Pull request review comments
+
+<Callout type="warn">
+GitHub App webhooks are configured during app creation. Make sure to select `application/json` as the content type.
+</Callout>
+
+## Thread model
+
+GitHub has two types of comment threads:
+
+| Type | Tab | Thread ID format |
+|------|-----|-----------------|
+| PR-level | Conversation | `github:{owner}/{repo}:{prNumber}` |
+| Review comments | Files Changed | `github:{owner}/{repo}:{prNumber}:rc:{commentId}` |
+
+## Reactions
+
+Supports GitHub's reaction emoji:
+
+| SDK emoji | GitHub reaction |
+|-----------|----------------|
+| `thumbs_up` | 👍 (+1) |
+| `thumbs_down` | 👎 (-1) |
+| `laugh` | 😄 |
+| `confused` | 😕 |
+| `heart` | ❤️ |
+| `hooray` | 🎉 |
+| `rocket` | 🚀 |
+| `eyes` | 👀 |
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `token` | Yes* | Personal Access Token with `repo` scope |
+| `appId` | Yes* | GitHub App ID |
+| `privateKey` | For Apps | GitHub App private key (PEM format) |
+| `installationId` | No | Installation ID (omit for multi-tenant) |
+| `webhookSecret` | Yes | Webhook secret for signature verification |
+| `userName` | Yes | Bot username for @mention detection |
+| `botUserId` | No | Bot's numeric user ID (auto-detected if not provided) |
+
+*Either `token` or `appId`/`privateKey` is required.
+
+## Environment variables
+
+```bash title=".env.local"
+# Personal Access Token auth
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+
+# OR GitHub App auth
+GITHUB_APP_ID=123456
+GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
+GITHUB_INSTALLATION_ID=12345678  # Optional for multi-tenant
+
+# Required
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+```
+
+## Features
+
+| Feature | Supported |
+|---------|-----------|
+| Mentions | Yes |
+| Reactions (add/remove) | Yes |
+| Cards | GFM Markdown |
+| Modals | No |
+| Streaming | No |
+| DMs | No |
+| File uploads | No |
+| Typing indicator | No |
+| Message history | Yes |
+| Multi-tenant | Yes (GitHub App) |
+
+## Limitations
+
+- **No typing indicators** — GitHub doesn't support typing indicators
+- **No streaming** — Messages posted in full (editing supported for updates)
+- **No DMs** — GitHub doesn't have direct messages
+- **No modals** — GitHub doesn't support interactive modals
+- **Action buttons** — Rendered as text; use link buttons for clickable actions
+
+## Troubleshooting
+
+### "Invalid signature" error
+
+- Verify `GITHUB_WEBHOOK_SECRET` matches your webhook configuration
+- Ensure the request body isn't modified before verification
+
+### "Invalid JSON" error
+
+- Change webhook **Content type** to `application/json`
+
+### Bot not responding to mentions
+
+- Verify webhook events are configured (issue_comment, pull_request_review_comment)
+- Check the webhook URL is correct and accessible
+- Ensure the `userName` config matches your bot's GitHub username
+
+### "Installation ID required" error
+
+- This occurs when making API calls outside webhook context in multi-tenant mode
+- Use a persistent state adapter (Redis) to store installation mappings
+- The first interaction must come from a webhook to establish the mapping
+
+### Rate limiting
+
+- PATs have lower rate limits than GitHub Apps
+- Consider switching to a GitHub App for production use

package/docs/adapters/index.mdx

@@ -0,0 +1,110 @@
+---
+title: Overview
+description: Platform-specific adapters for Slack, Teams, Google Chat, Discord, GitHub, and Linear.
+type: overview
+prerequisites:
+  - /docs/getting-started
+---
+
+Adapters handle webhook verification, message parsing, and API calls for each platform. Install only the adapters you need.
+
+## Feature matrix
+
+### Messaging
+
+| Feature | [Slack](/docs/adapters/slack) | [Teams](/docs/adapters/teams) | [Google Chat](/docs/adapters/gchat) | [Discord](/docs/adapters/discord) | [GitHub](/docs/adapters/github) | [Linear](/docs/adapters/linear) |
+|---------|-------|-------|-------------|---------|--------|--------|
+| Post message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Edit message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Delete message | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| File uploads | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
+| Streaming | ✅ Native | ⚠️ Post+Edit | ⚠️ Post+Edit | ⚠️ Post+Edit | ❌ | ❌ |
+
+### Rich content
+
+| Feature | Slack | Teams | Google Chat | Discord | GitHub | Linear |
+|---------|-------|-------|-------------|---------|--------|--------|
+| Card format | Block Kit | Adaptive Cards | Google Chat Cards | Embeds | GFM Markdown | Markdown |
+| Buttons | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Link buttons | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Select menus | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
+| Fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Images in cards | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Modals | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+### Conversations
+
+| Feature | Slack | Teams | Google Chat | Discord | GitHub | Linear |
+|---------|-------|-------|-------------|---------|--------|--------|
+| Mentions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Add reactions | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
+| Remove reactions | ✅ | ❌ | ✅ | ✅ | ⚠️ | ⚠️ |
+| Typing indicator | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ |
+| DMs | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+| Ephemeral messages | ✅ Native | ❌ | ✅ Native | ❌ | ❌ | ❌ |
+
+### Message history
+
+| Feature | Slack | Teams | Google Chat | Discord | GitHub | Linear |
+|---------|-------|-------|-------------|---------|--------|--------|
+| Fetch messages | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Fetch single message | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Fetch thread info | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Fetch channel messages | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| List threads | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Fetch channel info | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
+| Post channel message | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
+
+<Callout type="info">
+⚠️ indicates partial support — the feature works with limitations. See individual adapter pages for details.
+</Callout>
+
+## Packages
+
+| Platform | Package |
+|----------|---------|
+| [Slack](/docs/adapters/slack) | `@chat-adapter/slack` |
+| [Microsoft Teams](/docs/adapters/teams) | `@chat-adapter/teams` |
+| [Google Chat](/docs/adapters/gchat) | `@chat-adapter/gchat` |
+| [Discord](/docs/adapters/discord) | `@chat-adapter/discord` |
+| [GitHub](/docs/adapters/github) | `@chat-adapter/github` |
+| [Linear](/docs/adapters/linear) | `@chat-adapter/linear` |
+
+## How adapters work
+
+Each adapter implements a standard interface that the `Chat` class uses to route events and send messages. When a webhook arrives:
+
+1. The adapter verifies the request signature
+2. Parses the platform-specific payload into a normalized `Message`
+3. Routes to your handlers via the `Chat` class
+4. Converts outgoing messages from markdown/AST/cards to the platform's native format
+
+## Using multiple adapters
+
+Register multiple adapters and your event handlers work across all of them:
+
+```typescript title="lib/bot.ts" lineNumbers
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createTeamsAdapter } from "@chat-adapter/teams";
+import { createGoogleChatAdapter } from "@chat-adapter/gchat";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter({ /* ... */ }),
+    teams: createTeamsAdapter({ /* ... */ }),
+    gchat: createGoogleChatAdapter({ /* ... */ }),
+  },
+  state: createRedisState({ url: process.env.REDIS_URL! }),
+});
+
+// This handler fires for mentions on any platform
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello!");
+});
+```
+
+Each adapter creates a webhook handler accessible via `bot.webhooks.slack`, `bot.webhooks.teams`, etc.