@chat-adapter/linear 4.8.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# @chat-adapter/linear
+
+Linear adapter for the [chat](https://github.com/vercel-labs/chat) SDK. Enables bots to respond to @mentions in Linear issue comment threads.
+
+## Installation
+
+```bash
+npm install chat @chat-adapter/linear
+```
+
+## Usage
+
+```typescript
+import { Chat } from "chat";
+import { createLinearAdapter } from "@chat-adapter/linear";
+import { MemoryState } from "@chat-adapter/state-memory";
+
+const chat = new Chat({
+  userName: "my-bot",
+  adapters: {
+    linear: createLinearAdapter({
+      apiKey: process.env.LINEAR_API_KEY!,
+      webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+      userName: "my-bot",
+      logger: console,
+    }),
+  },
+  state: new MemoryState(),
+  logger: "info",
+});
+
+// Handle @mentions in issue comments
+chat.onNewMention(async (thread, message) => {
+  await thread.post("Hello from Linear!");
+});
+```
+
+## Configuration
+
+| Option          | Required | Description                                                                                         |
+| --------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `apiKey`        | Yes\*    | [Personal API key](https://linear.app/docs/api-and-webhooks) from Settings > Security & Access      |
+| `clientId`      | Yes\*    | [OAuth app](https://linear.app/developers/oauth-2-0-authentication) client ID                       |
+| `clientSecret`  | Yes\*    | OAuth app client secret                                                                             |
+| `accessToken`   | Yes\*    | Pre-obtained [OAuth access token](https://linear.app/developers/oauth-2-0-authentication)           |
+| `webhookSecret` | Yes      | [Webhook signing secret](https://linear.app/developers/webhooks#securing-webhooks) for verification |
+| `userName`      | Yes      | Bot display name for @mention detection                                                             |
+
+\*One of: `apiKey`, `clientId`/`clientSecret`, or `accessToken` is required.
+
+## Environment Variables
+
+```bash
+# API Key auth (simplest)
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
+
+# OR OAuth app auth (recommended for production)
+LINEAR_CLIENT_ID=your-client-id
+LINEAR_CLIENT_SECRET=your-client-secret
+
+# Webhook secret (required for all auth methods)
+LINEAR_WEBHOOK_SECRET=your-webhook-secret
+```
+
+## Linear Setup
+
+### Option A: Personal API Key
+
+Best for personal projects, testing, or single-workspace bots.
+
+1. Go to [Settings > Security & Access](https://linear.app/settings/account/security) in Linear
+2. Scroll to **Personal API keys** and click **Create key**
+3. Select **Only select permissions** and enable:
+   - **Create issues** - Create and update issues
+   - **Create comments** - Create and update issue comments
+4. Under **Team access**, choose **All teams** or select specific teams
+5. Click **Create** and set `LINEAR_API_KEY` environment variable
+
+> **Note:** When using a personal API key, all actions are attributed to you as an individual.
+
+### Option B: OAuth Application (Recommended for Apps)
+
+Use this if you want the bot to have its **own identity** in Linear (not attributed to you personally), or if you're building a public integration. The adapter handles token management internally -- no need to store tokens.
+
+1. Go to [Settings > API > Applications](https://linear.app/settings/api/applications/new) in Linear
+2. Create a new OAuth2 application with your bot's name and icon
+3. **Enable client credentials tokens** in the app settings
+4. Note your **Client ID** and **Client Secret**
+5. Set `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET` environment variables
+
+```typescript
+createLinearAdapter({
+  clientId: process.env.LINEAR_CLIENT_ID!,
+  clientSecret: process.env.LINEAR_CLIENT_SECRET!,
+  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+  userName: "my-bot",
+  logger: console,
+});
+```
+
+The adapter uses the [client credentials grant](https://linear.app/developers/oauth-2-0-authentication#client-credentials-tokens) to obtain tokens automatically. Tokens are valid for 30 days and auto-refresh when expired.
+
+> **When to use which?**
+>
+> - **API Key** -- Personal projects, testing, single workspace. Actions attributed to you.
+> - **OAuth App** -- Production bots, public integrations, bot has its own identity.
+> - For making the bot `@`-mentionable as an [Agent](https://linear.app/developers/agents), see the [OAuth setup guide](#oauth-setup-guide) below.
+
+### Webhook Setup
+
+See the [Linear Webhooks documentation](https://linear.app/developers/webhooks) for detailed instructions.
+
+> **Note:** 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.
+
+1. Go to **Settings > API** in your Linear workspace and click **Create webhook**
+2. Fill in:
+   - **Label**: A descriptive name (e.g., "Chat Bot")
+   - **URL**: `https://your-domain.com/api/webhooks/linear`
+3. Copy the **Signing secret** and set it as `LINEAR_WEBHOOK_SECRET`
+4. Under **Data change events**, select:
+   - **Comments** (required - for issue comments)
+   - **Issues** (recommended - for mentions in issue descriptions)
+   - **Emoji reactions** (optional - for reaction handling)
+5. Under **Team selection**, choose **All public teams** or a specific team
+6. Click **Create webhook**
+
+## Features
+
+- Message posting and editing
+- Message deletion
+- [Reaction handling](https://linear.app/docs/comment-on-issues) (add reactions via emoji)
+- Issue comment threads
+- Cards (rendered as [Markdown](https://linear.app/docs/comment-on-issues))
+
+## Thread Model
+
+Linear has two levels of comment threading:
+
+| Type           | Description                             | Thread ID Format                 |
+| -------------- | --------------------------------------- | -------------------------------- |
+| Issue-level    | Top-level comments on an issue          | `linear:{issueId}`               |
+| Comment thread | Replies nested under a specific comment | `linear:{issueId}:c:{commentId}` |
+
+When a user writes a comment, the bot replies **within the same comment thread** (nested under the same card). This matches the expected Linear UX where conversations are grouped.
+
+Example thread IDs:
+
+- `linear:2174add1-f7c8-44e3-bbf3-2d60b5ea8bc9` (issue-level)
+- `linear:2174add1-f7c8-44e3-bbf3-2d60b5ea8bc9:c:comment-abc123` (comment thread)
+
+## Reactions
+
+Linear supports standard [emoji reactions](https://linear.app/docs/comment-on-issues) on comments. The adapter maps SDK emoji names to unicode:
+
+| SDK Emoji     | Linear Emoji |
+| ------------- | ------------ |
+| `thumbs_up`   | 👍           |
+| `thumbs_down` | 👎           |
+| `heart`       | ❤️           |
+| `fire`        | 🔥           |
+| `rocket`      | 🚀           |
+| `eyes`        | 👀           |
+| `sparkles`    | ✨           |
+| `wave`        | 👋           |
+
+## Limitations
+
+- **No typing indicators** - Linear doesn't support typing indicators
+- **No streaming** - Messages posted in full (editing supported for updates)
+- **No DMs** - Linear doesn't have direct messages
+- **No modals** - Linear doesn't support interactive modals
+- **Action buttons** - Rendered as text; use link buttons for clickable actions
+- **Remove reaction** - Requires reaction ID lookup (not directly supported)
+
+## Troubleshooting
+
+### "Invalid signature" error
+
+- Verify `LINEAR_WEBHOOK_SECRET` matches the secret from your webhook configuration
+- Ensure the request body isn't being modified before verification
+- The webhook secret is shown only once at creation - regenerate if lost
+
+### Bot not responding to mentions
+
+- Verify webhook events are configured with `Comment` resource type
+- Check that the webhook URL is correct and accessible
+- Ensure the `userName` config matches how users mention the bot
+- Check that the webhook is enabled (Linear may auto-disable after repeated failures)
+
+### "Webhook expired" error
+
+- This means the webhook timestamp is too old (> 5 minutes)
+- Usually indicates a delivery delay or clock skew
+- Check that your server time is synchronized
+
+### Rate limiting
+
+- Linear API has [rate limits](https://linear.app/developers/graphql#rate-limiting)
+- The SDK handles rate limiting automatically in most cases
+
+## OAuth Setup Guide
+
+This section is only relevant if you chose [Option B: OAuth Application](#option-b-oauth-application-recommended-for-apps). If you're using a personal API key (Option A), you can skip this entirely.
+
+Setting up an OAuth application gives the bot its own identity in Linear rather than acting as your personal account.
+
+### 1. Create the OAuth Application
+
+1. Go to [Settings > API > Applications](https://linear.app/settings/api/applications/new) in Linear (requires admin)
+2. Fill in:
+   - **Application name**: Your bot's name (e.g., "v0") -- this is how it appears in Linear
+   - **Application icon**: Upload an icon for the bot
+   - **Redirect callback URLs**: Add a placeholder URL (e.g., `https://your-domain.com/callback`) -- not needed for client credentials auth
+3. Click **Create**
+4. **Enable client credentials tokens** in the app settings
+5. Note your **Client ID** and **Client Secret**
+
+### 2. Configure the Adapter
+
+```typescript
+createLinearAdapter({
+  clientId: process.env.LINEAR_CLIENT_ID!,
+  clientSecret: process.env.LINEAR_CLIENT_SECRET!,
+  webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+  userName: "v0",
+  logger: console,
+});
+```
+
+That's it. The adapter automatically obtains and refreshes tokens using the [client credentials grant](https://linear.app/developers/oauth-2-0-authentication#client-credentials-tokens). No callback endpoints, no token storage, no refresh logic on your end.
+
+### 3. Making the Bot @-Mentionable (Optional)
+
+To make the bot appear in Linear's `@` mention dropdown as an [Agent](https://linear.app/developers/agents):
+
+1. In your OAuth app settings, enable **Agent session events** under webhooks
+2. Have a workspace admin install the app using `actor=app` with the `app:mentionable` scope:
+
+```
+https://linear.app/oauth/authorize?
+  client_id=YOUR_CLIENT_ID&
+  redirect_uri=https://your-domain.com/callback&
+  response_type=code&
+  scope=read,write,comments:create,app:mentionable&
+  actor=app
+```
+
+Once installed, the bot shows up as a mentionable user in the workspace. See the [Linear Agents docs](https://linear.app/developers/agents) for full details.
+
+For more on Linear OAuth, see the [Linear OAuth 2.0 documentation](https://linear.app/developers/oauth-2-0-authentication).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+import { Logger, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, EmojiValue, FetchOptions, FetchResult, ThreadInfo, Message, FormattedContent } from 'chat';
+
+/**
+ * Type definitions for the Linear adapter.
+ *
+ * Uses types from @linear/sdk wherever possible.
+ * Only defines adapter-specific config, thread IDs, and webhook payloads.
+ */
+
+/**
+ * Base configuration options shared by all auth methods.
+ */
+interface LinearAdapterBaseConfig {
+    /** Logger instance for error reporting */
+    logger: Logger;
+    /**
+     * Webhook signing secret for HMAC-SHA256 verification.
+     * Found on the webhook detail page in Linear settings.
+     */
+    webhookSecret: string;
+    /**
+     * Bot display name used for @-mention detection.
+     * For API key auth, this is typically the user's display name.
+     * For OAuth app auth with actor=app, this is the app name.
+     */
+    userName: string;
+}
+/**
+ * Configuration using a personal API key.
+ * Simplest setup, suitable for personal bots or testing.
+ *
+ * @see https://linear.app/docs/api-and-webhooks
+ */
+interface LinearAdapterAPIKeyConfig extends LinearAdapterBaseConfig {
+    /** Personal API key from Linear Settings > Security & Access */
+    apiKey: string;
+    accessToken?: never;
+}
+/**
+ * Configuration using an OAuth access token (pre-obtained).
+ * Use this if you've already obtained an access token through the OAuth flow.
+ *
+ * @see https://linear.app/developers/oauth-2-0-authentication
+ */
+interface LinearAdapterOAuthConfig extends LinearAdapterBaseConfig {
+    /** OAuth access token obtained through the OAuth flow */
+    accessToken: string;
+    apiKey?: never;
+    clientId?: never;
+    clientSecret?: never;
+}
+/**
+ * Configuration using OAuth client credentials (recommended for apps).
+ * The adapter handles token management internally - no need to store tokens.
+ *
+ * Uses the client_credentials grant type to obtain an app-level token.
+ * The token is valid for 30 days and auto-refreshes on 401.
+ *
+ * @see https://linear.app/developers/oauth-2-0-authentication#client-credentials-tokens
+ */
+interface LinearAdapterAppConfig extends LinearAdapterBaseConfig {
+    /** OAuth application client ID */
+    clientId: string;
+    /** OAuth application client secret */
+    clientSecret: string;
+    apiKey?: never;
+    accessToken?: never;
+}
+/**
+ * Linear adapter configuration - API Key, OAuth token, or OAuth App (client credentials).
+ */
+type LinearAdapterConfig = LinearAdapterAPIKeyConfig | LinearAdapterOAuthConfig | LinearAdapterAppConfig;
+/**
+ * Decoded thread ID for Linear.
+ *
+ * Thread types:
+ * - Issue-level: Top-level comments on the issue (no commentId)
+ * - Comment thread: Replies nested under a specific root comment (has commentId)
+ */
+interface LinearThreadId {
+    /** Linear issue UUID */
+    issueId: string;
+    /**
+     * Root comment ID for comment-level threads.
+     * If present, this is a comment thread (replies nest under this comment).
+     * If absent, this is an issue-level thread (top-level comment).
+     */
+    commentId?: string;
+}
+/**
+ * Comment data from a webhook payload.
+ *
+ * Verified against Linear's Webhooks Schema Explorer and
+ * example payloads from the official documentation.
+ *
+ * @see https://linear.app/developers/webhooks#webhook-payload
+ */
+interface LinearCommentData {
+    /** Comment UUID */
+    id: string;
+    /** Comment body in markdown format */
+    body: string;
+    /** Issue UUID the comment is associated with */
+    issueId: string;
+    /** User UUID who wrote the comment */
+    userId: string;
+    /** Parent comment UUID (for nested/threaded replies) */
+    parentId?: string;
+    /** ISO 8601 creation date */
+    createdAt: string;
+    /** ISO 8601 last update date */
+    updatedAt: string;
+    /** Direct URL to the comment */
+    url?: string;
+}
+/**
+ * Platform-specific raw message type for Linear.
+ */
+interface LinearRawMessage {
+    /** The raw comment data from webhook or API */
+    comment: LinearCommentData;
+    /** Organization ID from the webhook */
+    organizationId?: string;
+}
+
+/**
+ * Linear adapter for chat SDK.
+ *
+ * Supports comment threads on Linear issues.
+ * Authentication via personal API key or OAuth access token.
+ *
+ * @example API Key auth
+ * ```typescript
+ * import { Chat } from "chat";
+ * import { createLinearAdapter } from "@chat-adapter/linear";
+ * import { MemoryState } from "@chat-adapter/state-memory";
+ *
+ * const chat = new Chat({
+ *   userName: "my-bot",
+ *   adapters: {
+ *     linear: createLinearAdapter({
+ *       apiKey: process.env.LINEAR_API_KEY!,
+ *       webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+ *       userName: "my-bot",
+ *       logger: console,
+ *     }),
+ *   },
+ *   state: new MemoryState(),
+ *   logger: "info",
+ * });
+ * ```
+ *
+ * @example OAuth auth
+ * ```typescript
+ * const chat = new Chat({
+ *   userName: "my-bot",
+ *   adapters: {
+ *     linear: createLinearAdapter({
+ *       accessToken: process.env.LINEAR_ACCESS_TOKEN!,
+ *       webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+ *       userName: "my-bot",
+ *       logger: console,
+ *     }),
+ *   },
+ *   state: new MemoryState(),
+ *   logger: "info",
+ * });
+ * ```
+ */
+declare class LinearAdapter implements Adapter<LinearThreadId, LinearRawMessage> {
+    readonly name = "linear";
+    readonly userName: string;
+    private linearClient;
+    private webhookSecret;
+    private chat;
+    private logger;
+    private _botUserId;
+    private formatConverter;
+    private clientCredentials;
+    private accessTokenExpiry;
+    /** Bot user ID used for self-message detection */
+    get botUserId(): string | undefined;
+    constructor(config: LinearAdapterConfig);
+    initialize(chat: ChatInstance): Promise<void>;
+    /**
+     * Fetch a new access token using client credentials grant.
+     * The token is valid for 30 days. The adapter auto-refreshes on 401.
+     *
+     * @see https://linear.app/developers/oauth-2-0-authentication#client-credentials-tokens
+     */
+    private refreshClientCredentialsToken;
+    /**
+     * Ensure the client credentials token is still valid. Refresh if expired.
+     */
+    private ensureValidToken;
+    /**
+     * Handle incoming webhook from Linear.
+     *
+     * @see https://linear.app/developers/webhooks
+     */
+    handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    /**
+     * Verify Linear webhook signature using HMAC-SHA256.
+     *
+     * @see https://linear.app/developers/webhooks#securing-webhooks
+     */
+    private verifySignature;
+    /**
+     * Handle a new comment created on an issue.
+     *
+     * Threading logic:
+     * - If the comment has a parentId, it's a reply -> thread under the parent (root comment)
+     * - If no parentId, this is a root comment -> thread under this comment's own ID
+     */
+    private handleCommentCreated;
+    /**
+     * Handle reaction events (logging only - reactions don't include issueId).
+     */
+    private handleReaction;
+    /**
+     * Build a Message from a Linear comment and actor.
+     */
+    private buildMessage;
+    /**
+     * Post a message to a thread (create a comment on an issue).
+     *
+     * For comment-level threads, uses parentId to reply under the root comment.
+     * For issue-level threads, creates a top-level comment.
+     *
+     * Uses LinearClient.createComment({ issueId, body, parentId? }).
+     * @see https://linear.app/developers/sdk-fetching-and-modifying-data#mutations
+     */
+    postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<LinearRawMessage>>;
+    /**
+     * Edit an existing message (update a comment).
+     *
+     * Uses LinearClient.updateComment(id, { body }).
+     * @see https://linear.app/developers/sdk-fetching-and-modifying-data#mutations
+     */
+    editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<LinearRawMessage>>;
+    /**
+     * Delete a message (delete a comment).
+     *
+     * Uses LinearClient.deleteComment(id).
+     */
+    deleteMessage(_threadId: string, messageId: string): Promise<void>;
+    /**
+     * Add a reaction to a comment.
+     *
+     * Uses LinearClient.createReaction({ commentId, emoji }).
+     * Linear reactions use emoji strings (unicode).
+     */
+    addReaction(_threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Remove a reaction from a comment.
+     *
+     * Linear doesn't have a direct "remove reaction by emoji + user" API.
+     * Removing requires knowing the reaction ID, which would require fetching
+     * the comment's reactions first. This is a known limitation.
+     */
+    removeReaction(_threadId: string, _messageId: string, _emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Start typing indicator. Not supported by Linear.
+     */
+    startTyping(_threadId: string): Promise<void>;
+    /**
+     * Fetch messages from a thread.
+     *
+     * For issue-level threads: fetches all top-level issue comments.
+     * For comment-level threads: fetches the root comment and its children (replies).
+     */
+    fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<LinearRawMessage>>;
+    /**
+     * Fetch top-level comments on an issue.
+     */
+    private fetchIssueComments;
+    /**
+     * Fetch a comment thread (root comment + its children/replies).
+     */
+    private fetchCommentThread;
+    /**
+     * Convert an array of Linear SDK Comment objects to Message instances.
+     */
+    private commentsToMessages;
+    /**
+     * Fetch thread info for a Linear issue.
+     */
+    fetchThread(threadId: string): Promise<ThreadInfo>;
+    /**
+     * Encode a Linear thread ID.
+     *
+     * Formats:
+     * - Issue-level: linear:{issueId}
+     * - Comment thread: linear:{issueId}:c:{commentId}
+     */
+    encodeThreadId(platformData: LinearThreadId): string;
+    /**
+     * Decode a Linear thread ID.
+     *
+     * Formats:
+     * - Issue-level: linear:{issueId}
+     * - Comment thread: linear:{issueId}:c:{commentId}
+     */
+    decodeThreadId(threadId: string): LinearThreadId;
+    /**
+     * Parse platform message format to normalized format.
+     */
+    parseMessage(raw: LinearRawMessage): Message<LinearRawMessage>;
+    /**
+     * Render formatted content to Linear markdown.
+     */
+    renderFormatted(content: FormattedContent): string;
+    /**
+     * Resolve an emoji value to a unicode string.
+     * Linear uses standard unicode emoji for reactions.
+     */
+    private resolveEmoji;
+}
+/**
+ * Factory function to create a Linear adapter.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createLinearAdapter({
+ *   apiKey: process.env.LINEAR_API_KEY!,
+ *   webhookSecret: process.env.LINEAR_WEBHOOK_SECRET!,
+ *   userName: "my-bot",
+ *   logger: console,
+ * });
+ * ```
+ */
+declare function createLinearAdapter(config: LinearAdapterConfig): LinearAdapter;
+
+export { LinearAdapter, type LinearAdapterAPIKeyConfig, type LinearAdapterAppConfig, type LinearAdapterConfig, type LinearAdapterOAuthConfig, type LinearRawMessage, type LinearThreadId, createLinearAdapter };