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.
Files changed (44) hide show
  1. package/README.md +2 -0
  2. package/dist/{chunk-WAB7KMH4.js → chunk-JW7GYSMH.js} +3 -3
  3. package/dist/chunk-JW7GYSMH.js.map +1 -0
  4. package/dist/index.d.ts +220 -13
  5. package/dist/index.js +274 -56
  6. package/dist/index.js.map +1 -1
  7. package/dist/jsx-runtime.d.ts +1 -1
  8. package/dist/jsx-runtime.js +1 -1
  9. package/docs/adapters/whatsapp.mdx +222 -0
  10. package/docs/{adapters/index.mdx → adapters.mdx} +46 -65
  11. package/docs/api/channel.mdx +15 -0
  12. package/docs/api/index.mdx +1 -0
  13. package/docs/api/thread.mdx +50 -0
  14. package/docs/contributing/building.mdx +1 -0
  15. package/docs/error-handling.mdx +2 -2
  16. package/docs/getting-started.mdx +2 -0
  17. package/docs/guides/code-review-hono.mdx +3 -3
  18. package/docs/guides/discord-nuxt.mdx +3 -2
  19. package/docs/guides/durable-chat-sessions-nextjs.mdx +331 -0
  20. package/docs/guides/meta.json +7 -1
  21. package/docs/guides/scheduled-posts-neon.mdx +447 -0
  22. package/docs/guides/slack-nextjs.mdx +3 -2
  23. package/docs/index.mdx +3 -1
  24. package/docs/meta.json +3 -4
  25. package/docs/slash-commands.mdx +4 -4
  26. package/docs/{state/index.mdx → state.mdx} +24 -12
  27. package/docs/threads-messages-channels.mdx +17 -0
  28. package/docs/usage.mdx +5 -0
  29. package/package.json +1 -1
  30. package/dist/chunk-WAB7KMH4.js.map +0 -1
  31. package/docs/adapters/discord.mdx +0 -217
  32. package/docs/adapters/gchat.mdx +0 -237
  33. package/docs/adapters/github.mdx +0 -222
  34. package/docs/adapters/linear.mdx +0 -206
  35. package/docs/adapters/meta.json +0 -13
  36. package/docs/adapters/slack.mdx +0 -314
  37. package/docs/adapters/teams.mdx +0 -287
  38. package/docs/adapters/telegram.mdx +0 -161
  39. package/docs/state/ioredis.mdx +0 -81
  40. package/docs/state/memory.mdx +0 -52
  41. package/docs/state/meta.json +0 -4
  42. package/docs/state/postgres.mdx +0 -98
  43. package/docs/state/redis.mdx +0 -100
  44. package/dist/{jsx-runtime-BYavlUk9.d.ts → jsx-runtime-C2ATKxHQ.d.ts} +95 -95
@@ -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
@@ -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
@@ -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
@@ -1,13 +0,0 @@
1
- {
2
- "title": "Adapters",
3
- "pages": [
4
- "index",
5
- "slack",
6
- "teams",
7
- "gchat",
8
- "discord",
9
- "telegram",
10
- "github",
11
- "linear"
12
- ]
13
- }