feat: add @chat-adapter/zoom — Zoom Team Chat adapter

.changeset/add-zoom-adapter.md

@@ -0,0 +1,5 @@
+---
+"@chat-adapter/zoom": minor
+---
+
+Add Zoom Team Chat adapter (`@chat-adapter/zoom`) with webhook verification (CRC challenge + HMAC-SHA256), S2S OAuth chatbot token caching, inbound event parsing for `bot_notification` and `team_chat.app_mention`, outbound message posting/editing/deletion, bidirectional Zoom markdown ↔ mdast format conversion, and integration test fixtures.

.gitignore

@@ -41,4 +41,7 @@ todo/
 next-env.d.ts
 .source
 
-packages/chat/docs
+packages/chat/docs
+
+# GSD planning (local-only, not committed)
+.planning/

.npmrc

@@ -0,0 +1,4 @@
+# Route @zoom scope to public npm registry
+# The global npmrc points to Zoom's internal Artifactory, which doesn't
+# serve the @zoom/rivet tarballs in this environment.
+@zoom:registry=https://registry.npmjs.org/

apps/docs/adapters.json

@@ -79,6 +79,16 @@
     "beta": true,
     "readme": "https://github.com/vercel/chat/tree/main/packages/adapter-whatsapp"
   },
+  {
+    "name": "Zoom",
+    "slug": "zoom",
+    "type": "platform",
+    "description": "Build bots for Zoom Team Chat with webhook verification, message threading, and bidirectional markdown formatting.",
+    "packageName": "@chat-adapter/zoom",
+    "icon": "zoom",
+    "beta": true,
+    "readme": "https://github.com/vercel/chat/tree/main/packages/adapter-zoom"
+  },
   {
     "name": "Redis",
     "slug": "redis",

packages/adapter-zoom/README.md

@@ -0,0 +1,197 @@
+# @chat-adapter/zoom
+
+[![npm version](https://img.shields.io/npm/v/@chat-adapter/zoom)](https://www.npmjs.com/package/@chat-adapter/zoom)
+[![npm downloads](https://img.shields.io/npm/dm/@chat-adapter/zoom)](https://www.npmjs.com/package/@chat-adapter/zoom)
+
+Zoom Team Chat adapter for [Chat SDK](https://chat-sdk.dev)
+
+## Installation
+
+```bash
+pnpm add @chat-adapter/zoom
+```
+
+## Usage
+
+```typescript
+import { Chat } from "chat";
+import { createZoomAdapter } from "@chat-adapter/zoom";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    zoom: createZoomAdapter(),
+  },
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Zoom!");
+});
+```
+
+When using `createZoomAdapter()` without arguments, credentials are auto-detected from environment variables.
+
+## Zoom Marketplace app setup
+
+### Prerequisites
+
+- Zoom account with developer access
+- A deployed URL or ngrok tunnel for local testing (e.g. `https://your-domain.com`)
+
+### Steps
+
+1. **Create the app**
+   - Go to [marketplace.zoom.us](https://marketplace.zoom.us) → **Develop** → **Build App**
+   - Select **General App**
+   - In **Basic Information**, set management type to **Admin-managed**
+
+2. **Get core credentials** — from **Basic Information** → **App Credentials**
+   - Copy **Client ID** → `ZOOM_CLIENT_ID`
+   - Copy **Client Secret** → `ZOOM_CLIENT_SECRET`
+   - Copy **Account ID** → `ZOOM_ACCOUNT_ID`
+
+3. **Configure the bot endpoint and get Robot JID** — from **Surface** → **Team Chat Subscription**
+   - Enable **Team Chat Subscription**
+   - Set **Bot Endpoint URL** to `https://your-domain.com/api/webhooks/zoom`
+   - Copy the **Bot JID** that appears → `ZOOM_ROBOT_JID`
+
+4. **Get the webhook secret** — from **Features** → **Access** → **Token**
+   - Copy the **Secret Token** → `ZOOM_WEBHOOK_SECRET_TOKEN`
+
+5. **Add event subscriptions** — from **Features** → **Access** → **Event Subscription**
+   - Enable Event Subscription
+   - Set webhook URL to `https://your-domain.com/api/webhooks/zoom`
+   - Subscribe to: `bot_notification`, `team_chat.app_mention`
+
+6. **Add scopes** — from **Scopes** (see [Required scopes](#required-scopes) below)
+
+7. **Authorize the app** — from **Local Test** → **Add app now**
+   - Complete the OAuth flow to install the bot in your account
+
+### Environment variables checklist
+
+```bash
+ZOOM_CLIENT_ID=          # Basic Information → App Credentials
+ZOOM_CLIENT_SECRET=      # Basic Information → App Credentials
+ZOOM_ACCOUNT_ID=         # Basic Information → App Credentials
+ZOOM_ROBOT_JID=          # Surface → Team Chat Subscription → Bot JID
+ZOOM_WEBHOOK_SECRET_TOKEN= # Features → Access → Token → Secret Token
+```
+
+### Local testing with ngrok
+
+```bash
+ngrok http 3000
+# Use the https:// forwarding URL as your Bot Endpoint URL and event subscription URL
+```
+
+## Required scopes
+
+| Scope | Purpose |
+|-------|---------|
+| `imchat:bot` | Send bot messages to channels and DMs |
+| `team_chat:read:app_mention:admin` | Receive app_mention events |
+| `team_chat:write:message:admin` | Send, edit, and delete messages |
+
+## Webhook setup
+
+```typescript
+// app/api/webhooks/zoom/route.ts
+import { bot } from "@/lib/bot";
+import { after } from "next/server";
+
+export async function POST(request: Request) {
+  return bot.adapters.zoom.handleWebhook(request, { waitUntil: after });
+}
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ZOOM_CLIENT_ID` | Yes | OAuth app Client ID |
+| `ZOOM_CLIENT_SECRET` | Yes | OAuth app Client Secret |
+| `ZOOM_ACCOUNT_ID` | Yes | Zoom account ID (account-level app) |
+| `ZOOM_ROBOT_JID` | Yes | Bot's JID from Marketplace app settings |
+| `ZOOM_WEBHOOK_SECRET_TOKEN` | Yes | Webhook Secret Token from Event Subscriptions |
+| `ZOOM_BOT_USERNAME` | No | Bot username for self-message detection (defaults to `zoom-bot`) |
+
+## Configuration
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `clientId` | No* | OAuth app Client ID. Auto-detected from `ZOOM_CLIENT_ID` |
+| `clientSecret` | No* | OAuth app Client Secret. Auto-detected from `ZOOM_CLIENT_SECRET` |
+| `accountId` | No* | Zoom account ID. Auto-detected from `ZOOM_ACCOUNT_ID` |
+| `robotJid` | No* | Bot's JID. Auto-detected from `ZOOM_ROBOT_JID` |
+| `webhookSecretToken` | No* | Webhook secret token. Auto-detected from `ZOOM_WEBHOOK_SECRET_TOKEN` |
+| `userName` | No | Bot username. Auto-detected from `ZOOM_BOT_USERNAME` (defaults to `zoom-bot`) |
+| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
+
+*Required at runtime — either via config or environment variable.
+
+## Features
+
+### Messaging
+
+| Feature | Supported |
+|---------|-----------|
+| Post message | Yes |
+| Edit message | Yes |
+| Delete message | Yes |
+| Reply in thread | Yes |
+| Streaming | Buffered (accumulates then sends) |
+
+### Conversations
+
+| Feature | Supported |
+|---------|-----------|
+| DMs | Yes (via bot_notification) |
+| Channel slash commands | Yes (via bot_notification) |
+| Thread subscription (subscribe flow) | No (Zoom platform limitation — see Known Limitations) |
+| DM thread replies | No (Zoom platform limitation — see Known Limitations) |
+| Reactions | No (not implemented in v1) |
+| Typing indicator | No (Zoom has no typing indicator API) |
+
+## Thread ID format
+
+```
+zoom:{channelId}:{messageId}
+```
+
+Examples:
+- Channel message: `zoom:abc123@conference.xmpp.zoom.us:msg-id-456`
+- DM: `zoom:{userJid}:{event_ts}` (sender-based channel with event timestamp as message ID)
+
+## Known limitations
+
+**Thread subscription (subscribe flow):** The `thread.subscribe()` pattern does not work for Zoom. Each `bot_notification` arrives with a unique thread ID based on `event_ts` — Zoom provides no `reply_to` or `parent_message_id` field to link replies to the original message. This is a confirmed Zoom platform limitation (verified against `@zoom/rivet` SDK, which also has no thread reply handler). Subsequent replies in a thread cannot be detected as part of the same conversation.
+
+**DM thread replies (THRD-03):** Zoom does not fire `chat_message.replied` for 1:1 DM thread replies. The adapter cannot subscribe to or receive threaded replies in DMs.
+
+**Unicode HMAC verification bug (ZOOM-506645):** Zoom's servers may normalize Unicode characters (emoji, accented characters) differently before computing the HMAC. Payloads containing non-ASCII characters may fail signature verification. The adapter logs the raw body hex on verification failure to aid diagnosis. If this affects you, contact Zoom Support referencing ZOOM-506645.
+
+## Troubleshooting
+
+**Webhook signature verification fails**
+- Ensure you're reading the raw request body before any JSON parsing
+- Emoji or non-ASCII characters in payloads may fail HMAC verification due to a Zoom server-side Unicode normalization issue (ZOOM-506645) — check debug logs for raw body hex
+
+**Bot not receiving events**
+- Confirm the Bot Endpoint URL in **Surface → Team Chat Subscription** matches your deployment URL
+- Confirm the event subscription URL in **Features → Access → Event Subscription** matches too
+- Verify the app is installed via **Local Test → Add app now** (OAuth flow must complete)
+
+**Bot appears in Zoom but doesn't respond**
+- Check that `ZOOM_WEBHOOK_SECRET_TOKEN` matches the Secret Token in **Features → Access → Token**
+- Ensure the app is marked as **Admin-managed** in Basic Information
+
+**DM thread replies not received**
+- This is a confirmed Zoom platform limitation — `chat_message.replied` is not fired for 1:1 DM thread replies. See [Known limitations](#known-limitations).
+
+**`postMessage` returns 401**
+- The `/v2/im/chat/messages` endpoint requires a `client_credentials` token. Ensure you're not using `account_credentials` grant type.
+
+## License
+
+MIT

packages/adapter-zoom/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@chat-adapter/zoom",
+  "version": "0.1.0",
+  "description": "Zoom Team Chat adapter for chat-sdk",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@chat-adapter/shared": "workspace:*",
+    "chat": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^25.3.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel/chat.git",
+    "directory": "packages/adapter-zoom"
+  },
+  "homepage": "https://github.com/vercel/chat#readme",
+  "bugs": {
+    "url": "https://github.com/vercel/chat/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "chat",
+    "zoom",
+    "bot",
+    "adapter",
+    "messaging",
+    "team-chat"
+  ],
+  "license": "MIT"
+}