chat 4.18.0 → 4.20.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/dist/{chunk-WAB7KMH4.js → chunk-JW7GYSMH.js} +3 -3
- package/dist/chunk-JW7GYSMH.js.map +1 -0
- package/dist/index.d.ts +220 -13
- package/dist/index.js +274 -56
- package/dist/index.js.map +1 -1
- package/dist/jsx-runtime.d.ts +1 -1
- package/dist/jsx-runtime.js +1 -1
- package/docs/adapters/whatsapp.mdx +222 -0
- package/docs/{adapters/index.mdx → adapters.mdx} +46 -65
- package/docs/api/channel.mdx +15 -0
- package/docs/api/index.mdx +1 -0
- package/docs/api/thread.mdx +50 -0
- package/docs/contributing/building.mdx +1 -0
- package/docs/error-handling.mdx +2 -2
- package/docs/getting-started.mdx +2 -0
- package/docs/guides/code-review-hono.mdx +3 -3
- package/docs/guides/discord-nuxt.mdx +3 -2
- package/docs/guides/durable-chat-sessions-nextjs.mdx +331 -0
- package/docs/guides/meta.json +7 -1
- package/docs/guides/scheduled-posts-neon.mdx +447 -0
- package/docs/guides/slack-nextjs.mdx +3 -2
- package/docs/index.mdx +3 -1
- package/docs/meta.json +3 -4
- package/docs/slash-commands.mdx +4 -4
- package/docs/{state/index.mdx → state.mdx} +24 -12
- package/docs/threads-messages-channels.mdx +17 -0
- package/docs/usage.mdx +5 -0
- package/package.json +1 -1
- package/dist/chunk-WAB7KMH4.js.map +0 -1
- package/docs/adapters/discord.mdx +0 -217
- package/docs/adapters/gchat.mdx +0 -237
- package/docs/adapters/github.mdx +0 -222
- package/docs/adapters/linear.mdx +0 -206
- package/docs/adapters/meta.json +0 -13
- package/docs/adapters/slack.mdx +0 -314
- package/docs/adapters/teams.mdx +0 -287
- package/docs/adapters/telegram.mdx +0 -161
- package/docs/state/ioredis.mdx +0 -81
- package/docs/state/memory.mdx +0 -52
- package/docs/state/meta.json +0 -4
- package/docs/state/postgres.mdx +0 -98
- package/docs/state/redis.mdx +0 -100
- package/dist/{jsx-runtime-BYavlUk9.d.ts → jsx-runtime-C2ATKxHQ.d.ts} +95 -95
package/docs/adapters/gchat.mdx
DELETED
|
@@ -1,237 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Google Chat
|
|
3
|
-
description: Configure the Google Chat adapter with service account authentication and optional Pub/Sub.
|
|
4
|
-
type: integration
|
|
5
|
-
prerequisites:
|
|
6
|
-
- /docs/getting-started
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Installation
|
|
10
|
-
|
|
11
|
-
```sh title="Terminal"
|
|
12
|
-
pnpm add @chat-adapter/gchat
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
## Usage
|
|
16
|
-
|
|
17
|
-
The adapter auto-detects credentials from `GOOGLE_CHAT_CREDENTIALS` or `GOOGLE_CHAT_USE_ADC` environment variables:
|
|
18
|
-
|
|
19
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
20
|
-
import { Chat } from "chat";
|
|
21
|
-
import { createGoogleChatAdapter } from "@chat-adapter/gchat";
|
|
22
|
-
|
|
23
|
-
const bot = new Chat({
|
|
24
|
-
userName: "mybot",
|
|
25
|
-
adapters: {
|
|
26
|
-
gchat: createGoogleChatAdapter(),
|
|
27
|
-
},
|
|
28
|
-
});
|
|
29
|
-
|
|
30
|
-
bot.onNewMention(async (thread, message) => {
|
|
31
|
-
await thread.post("Hello from Google Chat!");
|
|
32
|
-
});
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## Google Chat setup
|
|
36
|
-
|
|
37
|
-
### 1. Create a GCP project
|
|
38
|
-
|
|
39
|
-
1. Go to [console.cloud.google.com](https://console.cloud.google.com)
|
|
40
|
-
2. Click the project dropdown then **New Project**
|
|
41
|
-
3. Enter project name and click **Create**
|
|
42
|
-
|
|
43
|
-
### 2. Enable required APIs
|
|
44
|
-
|
|
45
|
-
Go to **APIs & Services** then **Library** and enable:
|
|
46
|
-
|
|
47
|
-
- **Google Chat API**
|
|
48
|
-
- **Google Workspace Events API** (for receiving all messages)
|
|
49
|
-
- **Cloud Pub/Sub API** (for receiving all messages)
|
|
50
|
-
|
|
51
|
-
### 3. Create a service account
|
|
52
|
-
|
|
53
|
-
1. Go to **IAM & Admin** then **Service Accounts**
|
|
54
|
-
2. Click **Create Service Account**
|
|
55
|
-
3. Enter name and description
|
|
56
|
-
4. Click **Create and Continue**
|
|
57
|
-
5. Skip the optional steps, click **Done**
|
|
58
|
-
|
|
59
|
-
### 4. Create service account key
|
|
60
|
-
|
|
61
|
-
1. Click on your service account
|
|
62
|
-
2. Go to **Keys** tab
|
|
63
|
-
3. Click **Add Key** then **Create new key**
|
|
64
|
-
4. Select **JSON** and click **Create**
|
|
65
|
-
5. Copy the entire JSON content as `GOOGLE_CHAT_CREDENTIALS`
|
|
66
|
-
|
|
67
|
-
<Callout type="info">
|
|
68
|
-
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**.
|
|
69
|
-
</Callout>
|
|
70
|
-
|
|
71
|
-
### 5. Configure Google Chat app
|
|
72
|
-
|
|
73
|
-
1. Go to the [Chat API configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
|
|
74
|
-
2. Click **Configuration** and fill in:
|
|
75
|
-
- **App name**: Your bot's display name
|
|
76
|
-
- **Avatar URL**: URL to your bot's avatar
|
|
77
|
-
- **Description**: What your bot does
|
|
78
|
-
- **Interactive features**: Enable **Receive 1:1 messages** and **Join spaces and group conversations**
|
|
79
|
-
- **Connection settings**: Select **App URL**
|
|
80
|
-
- **App URL**: `https://your-domain.com/api/webhooks/gchat`
|
|
81
|
-
- **Visibility**: Choose who can discover your app
|
|
82
|
-
3. Click **Save**
|
|
83
|
-
|
|
84
|
-
### 6. Add bot to a space
|
|
85
|
-
|
|
86
|
-
1. Open Google Chat
|
|
87
|
-
2. Create or open a Space
|
|
88
|
-
3. Click the space name then **Manage apps & integrations**
|
|
89
|
-
4. Click **Add apps**, search for your app, and click **Add**
|
|
90
|
-
|
|
91
|
-
## Pub/Sub for all messages (optional)
|
|
92
|
-
|
|
93
|
-
By default, Google Chat only sends webhooks for @mentions. To receive all messages in a space, set up Workspace Events with Pub/Sub.
|
|
94
|
-
|
|
95
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
96
|
-
createGoogleChatAdapter({
|
|
97
|
-
pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
|
|
98
|
-
impersonateUser: process.env.GOOGLE_CHAT_IMPERSONATE_USER,
|
|
99
|
-
});
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
`GOOGLE_CHAT_PUBSUB_TOPIC` and `GOOGLE_CHAT_IMPERSONATE_USER` are also auto-detected from env vars, so you can omit them from config if the env vars are set.
|
|
103
|
-
|
|
104
|
-
### 1. Create Pub/Sub topic
|
|
105
|
-
|
|
106
|
-
1. Go to **Pub/Sub** then **Topics**
|
|
107
|
-
2. Click **Create Topic**
|
|
108
|
-
3. Enter topic ID (e.g., `chat-events`)
|
|
109
|
-
4. Uncheck **Add a default subscription**
|
|
110
|
-
5. Click **Create**
|
|
111
|
-
6. Copy the full topic name as `GOOGLE_CHAT_PUBSUB_TOPIC` (format: `projects/your-project-id/topics/chat-events`)
|
|
112
|
-
|
|
113
|
-
### 2. Grant Chat service account access
|
|
114
|
-
|
|
115
|
-
1. Go to your Pub/Sub topic
|
|
116
|
-
2. Click **Permissions** tab
|
|
117
|
-
3. Click **Add Principal**
|
|
118
|
-
4. Enter `chat-api-push@system.gserviceaccount.com`
|
|
119
|
-
5. Select role **Pub/Sub Publisher**
|
|
120
|
-
6. Click **Save**
|
|
121
|
-
|
|
122
|
-
### 3. Create push subscription
|
|
123
|
-
|
|
124
|
-
1. Go to **Pub/Sub** then **Subscriptions**
|
|
125
|
-
2. Click **Create Subscription**
|
|
126
|
-
3. Select your topic
|
|
127
|
-
4. Set **Delivery type** to Push
|
|
128
|
-
5. Set **Endpoint URL** to `https://your-domain.com/api/webhooks/gchat`
|
|
129
|
-
6. Click **Create**
|
|
130
|
-
|
|
131
|
-
### 4. Enable domain-wide delegation
|
|
132
|
-
|
|
133
|
-
Domain-wide delegation is required for creating Workspace Events subscriptions and initiating DMs.
|
|
134
|
-
|
|
135
|
-
**Step 1 — Enable delegation on the service account:**
|
|
136
|
-
|
|
137
|
-
1. Go to **IAM & Admin** then **Service Accounts**
|
|
138
|
-
2. Click on your service account
|
|
139
|
-
3. Check **Enable Google Workspace Domain-wide Delegation** and save
|
|
140
|
-
4. Copy the **Client ID** (a numeric ID, not the email)
|
|
141
|
-
|
|
142
|
-
**Step 2 — Authorize in Google Admin Console:**
|
|
143
|
-
|
|
144
|
-
1. Go to [Google Admin Console](https://admin.google.com)
|
|
145
|
-
2. Go to **Security** then **Access and data control** then **API controls**
|
|
146
|
-
3. Click **Manage Domain Wide Delegation** then **Add new**
|
|
147
|
-
4. Enter the numeric **Client ID** from Step 1
|
|
148
|
-
5. Add OAuth scopes (comma-separated, on one line):
|
|
149
|
-
```
|
|
150
|
-
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
|
|
151
|
-
```
|
|
152
|
-
6. Click **Authorize**
|
|
153
|
-
|
|
154
|
-
**Step 3 — Set environment variable:**
|
|
155
|
-
|
|
156
|
-
Set `GOOGLE_CHAT_IMPERSONATE_USER` to an admin user email in your domain (e.g., `admin@yourdomain.com`).
|
|
157
|
-
|
|
158
|
-
## Configuration
|
|
159
|
-
|
|
160
|
-
All options are auto-detected from environment variables when not provided.
|
|
161
|
-
|
|
162
|
-
| Option | Required | Description |
|
|
163
|
-
|--------|----------|-------------|
|
|
164
|
-
| `credentials` | No* | Service account credentials JSON. Auto-detected from `GOOGLE_CHAT_CREDENTIALS` |
|
|
165
|
-
| `useApplicationDefaultCredentials` | No | Use Application Default Credentials. Auto-detected from `GOOGLE_CHAT_USE_ADC` |
|
|
166
|
-
| `pubsubTopic` | No | Pub/Sub topic for Workspace Events. Auto-detected from `GOOGLE_CHAT_PUBSUB_TOPIC` |
|
|
167
|
-
| `impersonateUser` | No | User email for domain-wide delegation. Auto-detected from `GOOGLE_CHAT_IMPERSONATE_USER` |
|
|
168
|
-
| `auth` | No | Custom auth object (advanced) |
|
|
169
|
-
| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
|
|
170
|
-
|
|
171
|
-
*Either `credentials`, `GOOGLE_CHAT_CREDENTIALS` env var, `useApplicationDefaultCredentials`, or `GOOGLE_CHAT_USE_ADC=true` is required.
|
|
172
|
-
|
|
173
|
-
## Environment variables
|
|
174
|
-
|
|
175
|
-
```bash title=".env.local"
|
|
176
|
-
GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}
|
|
177
|
-
|
|
178
|
-
# Optional: for receiving all messages
|
|
179
|
-
GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-events
|
|
180
|
-
GOOGLE_CHAT_IMPERSONATE_USER=admin@yourdomain.com
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
## Features
|
|
184
|
-
|
|
185
|
-
| Feature | Supported |
|
|
186
|
-
|---------|-----------|
|
|
187
|
-
| Mentions | Yes |
|
|
188
|
-
| Reactions (add/remove) | Yes (via Workspace Events) |
|
|
189
|
-
| Cards (Google Chat Cards) | Yes |
|
|
190
|
-
| Modals | No |
|
|
191
|
-
| Streaming | Post+Edit fallback |
|
|
192
|
-
| DMs | Yes (requires delegation) |
|
|
193
|
-
| Ephemeral messages | Yes (native) |
|
|
194
|
-
| File uploads | Yes |
|
|
195
|
-
| Typing indicator | No |
|
|
196
|
-
| Message history | Yes |
|
|
197
|
-
|
|
198
|
-
## Limitations
|
|
199
|
-
|
|
200
|
-
- **Typing indicators**: Not supported by Google Chat API. `startTyping()` is a no-op.
|
|
201
|
-
- **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.
|
|
202
|
-
|
|
203
|
-
### Message history (`fetchMessages`)
|
|
204
|
-
|
|
205
|
-
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.
|
|
206
|
-
|
|
207
|
-
## Troubleshooting
|
|
208
|
-
|
|
209
|
-
### No webhook received
|
|
210
|
-
|
|
211
|
-
- Verify the App URL is correct in Google Chat configuration
|
|
212
|
-
- Check that the Chat API is enabled
|
|
213
|
-
- Ensure the service account has the necessary permissions
|
|
214
|
-
|
|
215
|
-
### Pub/Sub not working
|
|
216
|
-
|
|
217
|
-
- Verify `chat-api-push@system.gserviceaccount.com` has Pub/Sub Publisher role
|
|
218
|
-
- Check that the push subscription URL is correct
|
|
219
|
-
- Verify domain-wide delegation is configured with correct scopes
|
|
220
|
-
- Check `GOOGLE_CHAT_IMPERSONATE_USER` is a valid admin email
|
|
221
|
-
|
|
222
|
-
### "Permission denied" for Workspace Events
|
|
223
|
-
|
|
224
|
-
- Ensure domain-wide delegation is configured
|
|
225
|
-
- Verify the OAuth scopes are exactly as specified
|
|
226
|
-
- Check that the impersonated user has access to the spaces
|
|
227
|
-
|
|
228
|
-
### "Insufficient Permission" for DMs
|
|
229
|
-
|
|
230
|
-
- DMs require domain-wide delegation with `chat.spaces` and `chat.spaces.create` scopes
|
|
231
|
-
- Scope changes can take up to 24 hours to propagate
|
|
232
|
-
|
|
233
|
-
### Button clicks not received
|
|
234
|
-
|
|
235
|
-
- Verify **Interactive features** is enabled in the Google Chat app configuration
|
|
236
|
-
- Check that the App URL is correctly set and accessible
|
|
237
|
-
- Button clicks go to the same webhook URL as messages
|
package/docs/adapters/github.mdx
DELETED
|
@@ -1,222 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: GitHub
|
|
3
|
-
description: Configure the GitHub adapter to respond to @mentions in PR and issue comment threads.
|
|
4
|
-
type: integration
|
|
5
|
-
prerequisites:
|
|
6
|
-
- /docs/getting-started
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
The GitHub adapter treats issue and pull request comments as messages, and issues/PRs as threads.
|
|
10
|
-
|
|
11
|
-
## Installation
|
|
12
|
-
|
|
13
|
-
```sh title="Terminal"
|
|
14
|
-
pnpm add @chat-adapter/github
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Usage
|
|
18
|
-
|
|
19
|
-
The adapter auto-detects credentials from `GITHUB_TOKEN` (or `GITHUB_APP_ID`/`GITHUB_PRIVATE_KEY`), `GITHUB_WEBHOOK_SECRET`, and `GITHUB_BOT_USERNAME` environment variables:
|
|
20
|
-
|
|
21
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
22
|
-
import { Chat } from "chat";
|
|
23
|
-
import { createGitHubAdapter } from "@chat-adapter/github";
|
|
24
|
-
|
|
25
|
-
const bot = new Chat({
|
|
26
|
-
userName: "my-bot",
|
|
27
|
-
adapters: {
|
|
28
|
-
github: createGitHubAdapter(),
|
|
29
|
-
},
|
|
30
|
-
});
|
|
31
|
-
|
|
32
|
-
bot.onNewMention(async (thread, message) => {
|
|
33
|
-
await thread.post("Hello from GitHub!");
|
|
34
|
-
});
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
## Authentication
|
|
38
|
-
|
|
39
|
-
### Option A: Personal Access Token
|
|
40
|
-
|
|
41
|
-
Best for personal projects, testing, or single-repo bots.
|
|
42
|
-
|
|
43
|
-
1. Go to [Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
|
|
44
|
-
2. Create a new token with `repo` scope
|
|
45
|
-
3. Set `GITHUB_TOKEN` environment variable
|
|
46
|
-
|
|
47
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
48
|
-
createGitHubAdapter({
|
|
49
|
-
token: process.env.GITHUB_TOKEN!,
|
|
50
|
-
});
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
### Option B: GitHub App (recommended)
|
|
54
|
-
|
|
55
|
-
Better rate limits, security, and supports multiple installations.
|
|
56
|
-
|
|
57
|
-
**1. Create the app:**
|
|
58
|
-
|
|
59
|
-
1. Go to [Settings > Developer settings > GitHub Apps > New GitHub App](https://github.com/settings/apps/new)
|
|
60
|
-
2. Set **Webhook URL** to `https://your-domain.com/api/webhooks/github`
|
|
61
|
-
3. Generate and set a **Webhook secret**
|
|
62
|
-
4. Set permissions:
|
|
63
|
-
- Repository > Issues: Read & write
|
|
64
|
-
- Repository > Pull requests: Read & write
|
|
65
|
-
- Repository > Metadata: Read-only
|
|
66
|
-
5. Subscribe to events: Issue comment, Pull request review comment
|
|
67
|
-
6. Click **Create GitHub App**
|
|
68
|
-
7. Note the **App ID** and click **Generate a private key**
|
|
69
|
-
|
|
70
|
-
**2. Install the app:**
|
|
71
|
-
|
|
72
|
-
1. Go to your app's settings then **Install App**
|
|
73
|
-
2. Click **Install** and choose repositories
|
|
74
|
-
3. Note the **Installation ID** from the URL:
|
|
75
|
-
```
|
|
76
|
-
https://github.com/settings/installations/12345678
|
|
77
|
-
^^^^^^^^
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
**Single-tenant:**
|
|
81
|
-
|
|
82
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
83
|
-
createGitHubAdapter({
|
|
84
|
-
appId: process.env.GITHUB_APP_ID!,
|
|
85
|
-
privateKey: process.env.GITHUB_PRIVATE_KEY!,
|
|
86
|
-
installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!),
|
|
87
|
-
});
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
**Multi-tenant (omit `installationId`):**
|
|
91
|
-
|
|
92
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
93
|
-
createGitHubAdapter({
|
|
94
|
-
appId: process.env.GITHUB_APP_ID!,
|
|
95
|
-
privateKey: process.env.GITHUB_PRIVATE_KEY!,
|
|
96
|
-
});
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
The adapter automatically extracts installation IDs from webhooks and caches API clients per-installation.
|
|
100
|
-
|
|
101
|
-
## Webhook setup
|
|
102
|
-
|
|
103
|
-
For repository or organization webhooks:
|
|
104
|
-
|
|
105
|
-
1. Go to repository/org **Settings** then **Webhooks** then **Add webhook**
|
|
106
|
-
2. Set **Payload URL** to `https://your-domain.com/api/webhooks/github`
|
|
107
|
-
3. Set **Content type** to `application/json` (required — the default `application/x-www-form-urlencoded` does not work)
|
|
108
|
-
4. Set **Secret** to match your `webhookSecret`
|
|
109
|
-
5. Select events: Issue comments, Pull request review comments
|
|
110
|
-
|
|
111
|
-
<Callout type="warn">
|
|
112
|
-
GitHub App webhooks are configured during app creation. Make sure to select `application/json` as the content type.
|
|
113
|
-
</Callout>
|
|
114
|
-
|
|
115
|
-
## Thread model
|
|
116
|
-
|
|
117
|
-
GitHub has two types of comment threads:
|
|
118
|
-
|
|
119
|
-
| Type | Tab | Thread ID format |
|
|
120
|
-
|------|-----|-----------------|
|
|
121
|
-
| PR-level | Conversation | `github:{owner}/{repo}:{prNumber}` |
|
|
122
|
-
| Review comments | Files Changed | `github:{owner}/{repo}:{prNumber}:rc:{commentId}` |
|
|
123
|
-
|
|
124
|
-
## Reactions
|
|
125
|
-
|
|
126
|
-
Supports GitHub's reaction emoji:
|
|
127
|
-
|
|
128
|
-
| SDK emoji | GitHub reaction |
|
|
129
|
-
|-----------|----------------|
|
|
130
|
-
| `thumbs_up` | 👍 (+1) |
|
|
131
|
-
| `thumbs_down` | 👎 (-1) |
|
|
132
|
-
| `laugh` | 😄 |
|
|
133
|
-
| `confused` | 😕 |
|
|
134
|
-
| `heart` | ❤️ |
|
|
135
|
-
| `hooray` | 🎉 |
|
|
136
|
-
| `rocket` | 🚀 |
|
|
137
|
-
| `eyes` | 👀 |
|
|
138
|
-
|
|
139
|
-
## Configuration
|
|
140
|
-
|
|
141
|
-
All options are auto-detected from environment variables when not provided.
|
|
142
|
-
|
|
143
|
-
| Option | Required | Description |
|
|
144
|
-
|--------|----------|-------------|
|
|
145
|
-
| `token` | No* | Personal Access Token. Auto-detected from `GITHUB_TOKEN` |
|
|
146
|
-
| `appId` | No* | GitHub App ID. Auto-detected from `GITHUB_APP_ID` |
|
|
147
|
-
| `privateKey` | No | GitHub App private key (PEM). Auto-detected from `GITHUB_PRIVATE_KEY` |
|
|
148
|
-
| `installationId` | No | Installation ID (omit for multi-tenant). Auto-detected from `GITHUB_INSTALLATION_ID` |
|
|
149
|
-
| `webhookSecret` | No** | Webhook secret. Auto-detected from `GITHUB_WEBHOOK_SECRET` |
|
|
150
|
-
| `userName` | No | Bot username for @mention detection. Auto-detected from `GITHUB_BOT_USERNAME` (default: `"github-bot"`) |
|
|
151
|
-
| `botUserId` | No | Bot's numeric user ID (auto-detected if not provided) |
|
|
152
|
-
| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
|
|
153
|
-
|
|
154
|
-
*Either `token`/`GITHUB_TOKEN` or `appId`+`privateKey`/`GITHUB_APP_ID`+`GITHUB_PRIVATE_KEY` is required.
|
|
155
|
-
|
|
156
|
-
**`webhookSecret` is required — either via config or `GITHUB_WEBHOOK_SECRET` env var.
|
|
157
|
-
|
|
158
|
-
## Environment variables
|
|
159
|
-
|
|
160
|
-
```bash title=".env.local"
|
|
161
|
-
# Personal Access Token auth
|
|
162
|
-
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
|
|
163
|
-
|
|
164
|
-
# OR GitHub App auth
|
|
165
|
-
GITHUB_APP_ID=123456
|
|
166
|
-
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
|
|
167
|
-
GITHUB_INSTALLATION_ID=12345678 # Optional for multi-tenant
|
|
168
|
-
|
|
169
|
-
# Required
|
|
170
|
-
GITHUB_WEBHOOK_SECRET=your-webhook-secret
|
|
171
|
-
```
|
|
172
|
-
|
|
173
|
-
## Features
|
|
174
|
-
|
|
175
|
-
| Feature | Supported |
|
|
176
|
-
|---------|-----------|
|
|
177
|
-
| Mentions | Yes |
|
|
178
|
-
| Reactions (add/remove) | Yes |
|
|
179
|
-
| Cards | GFM Markdown |
|
|
180
|
-
| Modals | No |
|
|
181
|
-
| Streaming | No |
|
|
182
|
-
| DMs | No |
|
|
183
|
-
| File uploads | No |
|
|
184
|
-
| Typing indicator | No |
|
|
185
|
-
| Message history | Yes |
|
|
186
|
-
| Multi-tenant | Yes (GitHub App) |
|
|
187
|
-
|
|
188
|
-
## Limitations
|
|
189
|
-
|
|
190
|
-
- **No typing indicators** — GitHub doesn't support typing indicators
|
|
191
|
-
- **No streaming** — Messages posted in full (editing supported for updates)
|
|
192
|
-
- **No DMs** — GitHub doesn't have direct messages
|
|
193
|
-
- **No modals** — GitHub doesn't support interactive modals
|
|
194
|
-
- **Action buttons** — Rendered as text; use link buttons for clickable actions
|
|
195
|
-
|
|
196
|
-
## Troubleshooting
|
|
197
|
-
|
|
198
|
-
### "Invalid signature" error
|
|
199
|
-
|
|
200
|
-
- Verify `GITHUB_WEBHOOK_SECRET` matches your webhook configuration
|
|
201
|
-
- Ensure the request body isn't modified before verification
|
|
202
|
-
|
|
203
|
-
### "Invalid JSON" error
|
|
204
|
-
|
|
205
|
-
- Change webhook **Content type** to `application/json`
|
|
206
|
-
|
|
207
|
-
### Bot not responding to mentions
|
|
208
|
-
|
|
209
|
-
- Verify webhook events are configured (issue_comment, pull_request_review_comment)
|
|
210
|
-
- Check the webhook URL is correct and accessible
|
|
211
|
-
- Ensure the `userName` config matches your bot's GitHub username
|
|
212
|
-
|
|
213
|
-
### "Installation ID required" error
|
|
214
|
-
|
|
215
|
-
- This occurs when making API calls outside webhook context in multi-tenant mode
|
|
216
|
-
- Use a persistent state adapter (Redis) to store installation mappings
|
|
217
|
-
- The first interaction must come from a webhook to establish the mapping
|
|
218
|
-
|
|
219
|
-
### Rate limiting
|
|
220
|
-
|
|
221
|
-
- PATs have lower rate limits than GitHub Apps
|
|
222
|
-
- Consider switching to a GitHub App for production use
|
package/docs/adapters/linear.mdx
DELETED
|
@@ -1,206 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Linear
|
|
3
|
-
description: Configure the Linear adapter to respond to @mentions in issue comment threads.
|
|
4
|
-
type: integration
|
|
5
|
-
prerequisites:
|
|
6
|
-
- /docs/getting-started
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
The Linear adapter treats issue comments as messages and issues as threads.
|
|
10
|
-
|
|
11
|
-
## Installation
|
|
12
|
-
|
|
13
|
-
```sh title="Terminal"
|
|
14
|
-
pnpm add @chat-adapter/linear
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Usage
|
|
18
|
-
|
|
19
|
-
The adapter auto-detects credentials from `LINEAR_API_KEY` (or `LINEAR_CLIENT_ID`/`LINEAR_CLIENT_SECRET`), `LINEAR_WEBHOOK_SECRET`, and `LINEAR_BOT_USERNAME` environment variables:
|
|
20
|
-
|
|
21
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
22
|
-
import { Chat } from "chat";
|
|
23
|
-
import { createLinearAdapter } from "@chat-adapter/linear";
|
|
24
|
-
|
|
25
|
-
const bot = new Chat({
|
|
26
|
-
userName: "my-bot",
|
|
27
|
-
adapters: {
|
|
28
|
-
linear: createLinearAdapter(),
|
|
29
|
-
},
|
|
30
|
-
});
|
|
31
|
-
|
|
32
|
-
bot.onNewMention(async (thread, message) => {
|
|
33
|
-
await thread.post("Hello from Linear!");
|
|
34
|
-
});
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
## Authentication
|
|
38
|
-
|
|
39
|
-
### Option A: Personal API key
|
|
40
|
-
|
|
41
|
-
Best for personal projects, testing, or single-workspace bots. Actions are attributed to you as an individual.
|
|
42
|
-
|
|
43
|
-
1. Go to [Settings > Security & Access](https://linear.app/settings/account/security)
|
|
44
|
-
2. Under **Personal API keys**, click **Create key**
|
|
45
|
-
3. Select **Only select permissions** and enable Create issues, Create comments
|
|
46
|
-
4. Choose team access
|
|
47
|
-
5. Click **Create** and set `LINEAR_API_KEY`
|
|
48
|
-
|
|
49
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
50
|
-
createLinearAdapter({
|
|
51
|
-
apiKey: process.env.LINEAR_API_KEY!,
|
|
52
|
-
});
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
### Option B: OAuth application (recommended)
|
|
56
|
-
|
|
57
|
-
The bot gets its own identity in Linear. The adapter handles token management internally.
|
|
58
|
-
|
|
59
|
-
1. Go to [Settings > API > Applications](https://linear.app/settings/api/applications/new)
|
|
60
|
-
2. Create an OAuth2 application with your bot's name and icon
|
|
61
|
-
3. **Enable client credentials tokens** in the app settings
|
|
62
|
-
4. Note the **Client ID** and **Client Secret**
|
|
63
|
-
|
|
64
|
-
```typescript title="lib/bot.ts" lineNumbers
|
|
65
|
-
createLinearAdapter({
|
|
66
|
-
clientId: process.env.LINEAR_CLIENT_ID!,
|
|
67
|
-
clientSecret: process.env.LINEAR_CLIENT_SECRET!,
|
|
68
|
-
});
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
The adapter uses the client credentials grant to obtain tokens automatically. Tokens are valid for 30 days and auto-refresh when expired.
|
|
72
|
-
|
|
73
|
-
### Making the bot @-mentionable (optional)
|
|
74
|
-
|
|
75
|
-
To make the bot appear in Linear's `@` mention dropdown as an Agent:
|
|
76
|
-
|
|
77
|
-
1. In your OAuth app settings, enable **Agent session events** under webhooks
|
|
78
|
-
2. Have a workspace admin install the app with `actor=app` and the `app:mentionable` scope:
|
|
79
|
-
|
|
80
|
-
```
|
|
81
|
-
https://linear.app/oauth/authorize?
|
|
82
|
-
client_id=your_client_id&
|
|
83
|
-
redirect_uri=https://your-domain.com/callback&
|
|
84
|
-
response_type=code&
|
|
85
|
-
scope=read,write,comments:create,app:mentionable&
|
|
86
|
-
actor=app
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
See the [Linear Agents docs](https://linear.app/developers/agents) for full details.
|
|
90
|
-
|
|
91
|
-
## Webhook setup
|
|
92
|
-
|
|
93
|
-
<Callout type="info">
|
|
94
|
-
Webhook management requires workspace admin access. If you don't see the API settings page, ask a workspace admin to create the webhook for you.
|
|
95
|
-
</Callout>
|
|
96
|
-
|
|
97
|
-
1. Go to **Settings > API** and click **Create webhook**
|
|
98
|
-
2. Fill in:
|
|
99
|
-
- **Label**: A descriptive name (e.g., "Chat Bot")
|
|
100
|
-
- **URL**: `https://your-domain.com/api/webhooks/linear`
|
|
101
|
-
3. Copy the **Signing secret** as `LINEAR_WEBHOOK_SECRET`
|
|
102
|
-
4. Under **Data change events**, select:
|
|
103
|
-
- **Comments** (required)
|
|
104
|
-
- **Issues** (recommended)
|
|
105
|
-
- **Emoji reactions** (optional)
|
|
106
|
-
5. Under **Team selection**, choose **All public teams** or a specific team
|
|
107
|
-
6. Click **Create webhook**
|
|
108
|
-
|
|
109
|
-
## Thread model
|
|
110
|
-
|
|
111
|
-
Linear has two levels of comment threading:
|
|
112
|
-
|
|
113
|
-
| Type | Description | Thread ID format |
|
|
114
|
-
|------|-------------|-----------------|
|
|
115
|
-
| Issue-level | Top-level comments on an issue | `linear:{issueId}` |
|
|
116
|
-
| Comment thread | Replies nested under a specific comment | `linear:{issueId}:c:{commentId}` |
|
|
117
|
-
|
|
118
|
-
When a user writes a comment, the bot replies within the same comment thread.
|
|
119
|
-
|
|
120
|
-
## Reactions
|
|
121
|
-
|
|
122
|
-
| SDK emoji | Linear emoji |
|
|
123
|
-
|-----------|-------------|
|
|
124
|
-
| `thumbs_up` | 👍 |
|
|
125
|
-
| `thumbs_down` | 👎 |
|
|
126
|
-
| `heart` | ❤️ |
|
|
127
|
-
| `fire` | 🔥 |
|
|
128
|
-
| `rocket` | 🚀 |
|
|
129
|
-
| `eyes` | 👀 |
|
|
130
|
-
| `sparkles` | ✨ |
|
|
131
|
-
| `wave` | 👋 |
|
|
132
|
-
|
|
133
|
-
## Configuration
|
|
134
|
-
|
|
135
|
-
All options are auto-detected from environment variables when not provided.
|
|
136
|
-
|
|
137
|
-
| Option | Required | Description |
|
|
138
|
-
|--------|----------|-------------|
|
|
139
|
-
| `apiKey` | No* | Personal API key. Auto-detected from `LINEAR_API_KEY` |
|
|
140
|
-
| `clientId` | No* | OAuth app client ID. Auto-detected from `LINEAR_CLIENT_ID` |
|
|
141
|
-
| `clientSecret` | No* | OAuth app client secret. Auto-detected from `LINEAR_CLIENT_SECRET` |
|
|
142
|
-
| `accessToken` | No* | Pre-obtained OAuth access token. Auto-detected from `LINEAR_ACCESS_TOKEN` |
|
|
143
|
-
| `webhookSecret` | No** | Webhook signing secret. Auto-detected from `LINEAR_WEBHOOK_SECRET` |
|
|
144
|
-
| `userName` | No | Bot display name. Auto-detected from `LINEAR_BOT_USERNAME` (default: `"linear-bot"`) |
|
|
145
|
-
| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
|
|
146
|
-
|
|
147
|
-
*One of `apiKey`, `clientId`/`clientSecret`, or `accessToken` is required (via config or env vars).
|
|
148
|
-
|
|
149
|
-
**`webhookSecret` is required — either via config or `LINEAR_WEBHOOK_SECRET` env var.
|
|
150
|
-
|
|
151
|
-
## Environment variables
|
|
152
|
-
|
|
153
|
-
```bash title=".env.local"
|
|
154
|
-
# API Key auth
|
|
155
|
-
LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
|
|
156
|
-
|
|
157
|
-
# OR OAuth app auth
|
|
158
|
-
LINEAR_CLIENT_ID=your-client-id
|
|
159
|
-
LINEAR_CLIENT_SECRET=your-client-secret
|
|
160
|
-
|
|
161
|
-
# Required
|
|
162
|
-
LINEAR_WEBHOOK_SECRET=your-webhook-secret
|
|
163
|
-
```
|
|
164
|
-
|
|
165
|
-
## Features
|
|
166
|
-
|
|
167
|
-
| Feature | Supported |
|
|
168
|
-
|---------|-----------|
|
|
169
|
-
| Mentions | Yes |
|
|
170
|
-
| Reactions (add) | Yes |
|
|
171
|
-
| Cards | Markdown |
|
|
172
|
-
| Modals | No |
|
|
173
|
-
| Streaming | No |
|
|
174
|
-
| DMs | No |
|
|
175
|
-
| File uploads | No |
|
|
176
|
-
| Typing indicator | No |
|
|
177
|
-
| Message history | Yes |
|
|
178
|
-
|
|
179
|
-
## Limitations
|
|
180
|
-
|
|
181
|
-
- **No typing indicators** — Linear doesn't support typing indicators
|
|
182
|
-
- **No streaming** — Messages posted in full (editing supported for updates)
|
|
183
|
-
- **No DMs** — Linear doesn't have direct messages
|
|
184
|
-
- **No modals** — Linear doesn't support interactive modals
|
|
185
|
-
- **Action buttons** — Rendered as text; use link buttons for clickable actions
|
|
186
|
-
- **Remove reaction** — Requires reaction ID lookup (not directly supported)
|
|
187
|
-
|
|
188
|
-
## Troubleshooting
|
|
189
|
-
|
|
190
|
-
### "Invalid signature" error
|
|
191
|
-
|
|
192
|
-
- Verify `LINEAR_WEBHOOK_SECRET` matches the secret from your webhook configuration
|
|
193
|
-
- The webhook secret is shown only once at creation — regenerate if lost
|
|
194
|
-
|
|
195
|
-
### Bot not responding to mentions
|
|
196
|
-
|
|
197
|
-
- Verify webhook events are configured with **Comments** resource type
|
|
198
|
-
- Check that the webhook URL is correct and accessible
|
|
199
|
-
- Ensure the `userName` config matches how users mention the bot
|
|
200
|
-
- Linear may auto-disable webhooks after repeated failures
|
|
201
|
-
|
|
202
|
-
### "Webhook expired" error
|
|
203
|
-
|
|
204
|
-
- Webhook timestamp is too old (> 5 minutes)
|
|
205
|
-
- Usually indicates a delivery delay or clock skew
|
|
206
|
-
- Check that your server time is synchronized
|