@chat-adapter/linear 4.8.0

package/dist/index.js

@@ -0,0 +1,727 @@
+// src/index.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { extractCard, ValidationError } from "@chat-adapter/shared";
+import { LinearClient } from "@linear/sdk";
+import { convertEmojiPlaceholders, Message } from "chat";
+
+// src/cards.ts
+function cardToLinearMarkdown(card) {
+  const lines = [];
+  if (card.title) {
+    lines.push(`**${escapeMarkdown(card.title)}**`);
+  }
+  if (card.subtitle) {
+    lines.push(escapeMarkdown(card.subtitle));
+  }
+  if ((card.title || card.subtitle) && card.children.length > 0) {
+    lines.push("");
+  }
+  if (card.imageUrl) {
+    lines.push(`![](${card.imageUrl})`);
+    lines.push("");
+  }
+  for (let i = 0; i < card.children.length; i++) {
+    const child = card.children[i];
+    const childLines = renderChild(child);
+    if (childLines.length > 0) {
+      lines.push(...childLines);
+      if (i < card.children.length - 1) {
+        lines.push("");
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function renderChild(child) {
+  switch (child.type) {
+    case "text":
+      return renderText(child);
+    case "fields":
+      return renderFields(child);
+    case "actions":
+      return renderActions(child);
+    case "section":
+      return child.children.flatMap(renderChild);
+    case "image":
+      if (child.alt) {
+        return [`![${escapeMarkdown(child.alt)}](${child.url})`];
+      }
+      return [`![](${child.url})`];
+    case "divider":
+      return ["---"];
+    default:
+      return [];
+  }
+}
+function renderText(text) {
+  const content = text.content;
+  switch (text.style) {
+    case "bold":
+      return [`**${content}**`];
+    case "muted":
+      return [`_${content}_`];
+    default:
+      return [content];
+  }
+}
+function renderFields(fields) {
+  return fields.children.map(
+    (field) => `**${escapeMarkdown(field.label)}:** ${escapeMarkdown(field.value)}`
+  );
+}
+function renderActions(actions) {
+  const buttonTexts = actions.children.map((button) => {
+    if (button.type === "link-button") {
+      return `[${escapeMarkdown(button.label)}](${button.url})`;
+    }
+    return `**[${escapeMarkdown(button.label)}]**`;
+  });
+  return [buttonTexts.join(" \u2022 ")];
+}
+function escapeMarkdown(text) {
+  return text.replace(/\*/g, "\\*").replace(/_/g, "\\_").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+}
+
+// src/markdown.ts
+import {
+  BaseFormatConverter,
+  parseMarkdown,
+  stringifyMarkdown
+} from "chat";
+var LinearFormatConverter = class extends BaseFormatConverter {
+  /**
+   * Convert an AST to standard markdown.
+   * Linear uses standard markdown, so we use remark-stringify directly.
+   */
+  fromAst(ast) {
+    return stringifyMarkdown(ast).trim();
+  }
+  /**
+   * Parse markdown into an AST.
+   * Linear uses standard markdown, so we use the standard parser.
+   */
+  toAst(markdown) {
+    return parseMarkdown(markdown);
+  }
+  /**
+   * Render a postable message to Linear markdown string.
+   */
+  renderPostable(message) {
+    if (typeof message === "string") {
+      return message;
+    }
+    if ("raw" in message) {
+      return message.raw;
+    }
+    if ("markdown" in message) {
+      return this.fromMarkdown(message.markdown);
+    }
+    if ("ast" in message) {
+      return this.fromAst(message.ast);
+    }
+    return super.renderPostable(message);
+  }
+};
+
+// src/index.ts
+var LinearAdapter = class {
+  name = "linear";
+  userName;
+  linearClient;
+  webhookSecret;
+  chat = null;
+  logger;
+  _botUserId = null;
+  formatConverter = new LinearFormatConverter();
+  // Client credentials auth state
+  clientCredentials = null;
+  accessTokenExpiry = null;
+  /** Bot user ID used for self-message detection */
+  get botUserId() {
+    return this._botUserId ?? void 0;
+  }
+  constructor(config) {
+    this.webhookSecret = config.webhookSecret;
+    this.logger = config.logger;
+    this.userName = config.userName;
+    if ("apiKey" in config && config.apiKey) {
+      this.linearClient = new LinearClient({ apiKey: config.apiKey });
+    } else if ("accessToken" in config && config.accessToken) {
+      this.linearClient = new LinearClient({
+        accessToken: config.accessToken
+      });
+    } else if ("clientId" in config && config.clientId) {
+      this.clientCredentials = {
+        clientId: config.clientId,
+        clientSecret: config.clientSecret
+      };
+    } else {
+      throw new Error(
+        "LinearAdapter requires either apiKey, accessToken, or clientId/clientSecret"
+      );
+    }
+  }
+  async initialize(chat) {
+    this.chat = chat;
+    if (this.clientCredentials) {
+      await this.refreshClientCredentialsToken();
+    }
+    try {
+      const viewer = await this.linearClient.viewer;
+      this._botUserId = viewer.id;
+      this.logger.info("Linear auth completed", {
+        botUserId: this._botUserId,
+        displayName: viewer.displayName
+      });
+    } catch (error) {
+      this.logger.warn("Could not fetch Linear bot user ID", { error });
+    }
+  }
+  /**
+   * 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
+   */
+  async refreshClientCredentialsToken() {
+    if (!this.clientCredentials) return;
+    const { clientId, clientSecret } = this.clientCredentials;
+    const response = await fetch("https://api.linear.app/oauth/token", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: clientId,
+        client_secret: clientSecret,
+        scope: "read,write,comments:create,issues:create"
+      })
+    });
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw new Error(
+        `Failed to fetch Linear client credentials token: ${response.status} ${errorBody}`
+      );
+    }
+    const data = await response.json();
+    this.linearClient = new LinearClient({
+      accessToken: data.access_token
+    });
+    this.accessTokenExpiry = Date.now() + data.expires_in * 1e3 - 36e5;
+    this.logger.info("Linear client credentials token obtained", {
+      expiresIn: `${Math.round(data.expires_in / 86400)} days`
+    });
+  }
+  /**
+   * Ensure the client credentials token is still valid. Refresh if expired.
+   */
+  async ensureValidToken() {
+    if (this.clientCredentials && this.accessTokenExpiry && Date.now() > this.accessTokenExpiry) {
+      this.logger.info("Linear access token expired, refreshing...");
+      await this.refreshClientCredentialsToken();
+    }
+  }
+  /**
+   * Handle incoming webhook from Linear.
+   *
+   * @see https://linear.app/developers/webhooks
+   */
+  async handleWebhook(request, options) {
+    const body = await request.text();
+    this.logger.debug("Linear webhook raw body", {
+      body: body.substring(0, 500)
+    });
+    const signature = request.headers.get("linear-signature");
+    if (!this.verifySignature(body, signature)) {
+      return new Response("Invalid signature", { status: 401 });
+    }
+    let payload;
+    try {
+      payload = JSON.parse(body);
+    } catch {
+      this.logger.error("Linear webhook invalid JSON", {
+        contentType: request.headers.get("content-type"),
+        bodyPreview: body.substring(0, 200)
+      });
+      return new Response("Invalid JSON", { status: 400 });
+    }
+    if (payload.webhookTimestamp) {
+      const timeDiff = Math.abs(Date.now() - payload.webhookTimestamp);
+      if (timeDiff > 5 * 60 * 1e3) {
+        this.logger.warn("Linear webhook timestamp too old", {
+          webhookTimestamp: payload.webhookTimestamp,
+          timeDiff
+        });
+        return new Response("Webhook expired", { status: 401 });
+      }
+    }
+    if (payload.type === "Comment") {
+      const commentPayload = payload;
+      if (commentPayload.action === "create") {
+        this.handleCommentCreated(commentPayload, options);
+      }
+    } else if (payload.type === "Reaction") {
+      const reactionPayload = payload;
+      this.handleReaction(reactionPayload);
+    }
+    return new Response("ok", { status: 200 });
+  }
+  /**
+   * Verify Linear webhook signature using HMAC-SHA256.
+   *
+   * @see https://linear.app/developers/webhooks#securing-webhooks
+   */
+  verifySignature(body, signature) {
+    if (!signature) {
+      return false;
+    }
+    const computedSignature = createHmac("sha256", this.webhookSecret).update(body).digest("hex");
+    try {
+      return timingSafeEqual(
+        Buffer.from(computedSignature, "hex"),
+        Buffer.from(signature, "hex")
+      );
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * 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
+   */
+  handleCommentCreated(payload, options) {
+    if (!this.chat) {
+      this.logger.warn("Chat instance not initialized, ignoring comment");
+      return;
+    }
+    const { data, actor } = payload;
+    if (!data.issueId) {
+      this.logger.debug("Ignoring non-issue comment", {
+        commentId: data.id
+      });
+      return;
+    }
+    const rootCommentId = data.parentId || data.id;
+    const threadId = this.encodeThreadId({
+      issueId: data.issueId,
+      commentId: rootCommentId
+    });
+    const message = this.buildMessage(data, actor, threadId);
+    if (data.userId === this._botUserId) {
+      this.logger.debug("Ignoring message from self", {
+        messageId: data.id
+      });
+      return;
+    }
+    this.chat.processMessage(this, threadId, message, options);
+  }
+  /**
+   * Handle reaction events (logging only - reactions don't include issueId).
+   */
+  handleReaction(payload) {
+    if (!this.chat) {
+      return;
+    }
+    const { data, actor } = payload;
+    this.logger.debug("Received reaction webhook", {
+      reactionId: data.id,
+      emoji: data.emoji,
+      commentId: data.commentId,
+      action: payload.action,
+      actorName: actor.name
+    });
+  }
+  /**
+   * Build a Message from a Linear comment and actor.
+   */
+  buildMessage(comment, actor, threadId) {
+    const text = comment.body || "";
+    const author = {
+      userId: comment.userId,
+      userName: actor.name || "unknown",
+      fullName: actor.name || "unknown",
+      isBot: actor.type !== "user",
+      isMe: comment.userId === this._botUserId
+    };
+    const formatted = this.formatConverter.toAst(text);
+    const raw = {
+      comment,
+      organizationId: void 0
+    };
+    return new Message({
+      id: comment.id,
+      threadId,
+      text,
+      formatted,
+      raw,
+      author,
+      metadata: {
+        dateSent: comment.createdAt ? new Date(comment.createdAt) : /* @__PURE__ */ new Date(),
+        edited: comment.createdAt !== comment.updatedAt,
+        editedAt: comment.createdAt !== comment.updatedAt && comment.updatedAt ? new Date(comment.updatedAt) : void 0
+      },
+      attachments: []
+    });
+  }
+  /**
+   * 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
+   */
+  async postMessage(threadId, message) {
+    await this.ensureValidToken();
+    const { issueId, commentId } = this.decodeThreadId(threadId);
+    let body;
+    const card = extractCard(message);
+    if (card) {
+      body = cardToLinearMarkdown(card);
+    } else {
+      body = this.formatConverter.renderPostable(message);
+    }
+    body = convertEmojiPlaceholders(body, "linear");
+    const commentPayload = await this.linearClient.createComment({
+      issueId,
+      body,
+      parentId: commentId
+    });
+    const comment = await commentPayload.comment;
+    if (!comment) {
+      throw new Error("Failed to create comment on Linear issue");
+    }
+    return {
+      id: comment.id,
+      threadId,
+      raw: {
+        comment: {
+          id: comment.id,
+          body: comment.body,
+          issueId,
+          userId: this._botUserId || "",
+          createdAt: comment.createdAt.toISOString(),
+          updatedAt: comment.updatedAt.toISOString(),
+          url: comment.url
+        }
+      }
+    };
+  }
+  /**
+   * Edit an existing message (update a comment).
+   *
+   * Uses LinearClient.updateComment(id, { body }).
+   * @see https://linear.app/developers/sdk-fetching-and-modifying-data#mutations
+   */
+  async editMessage(threadId, messageId, message) {
+    await this.ensureValidToken();
+    const { issueId } = this.decodeThreadId(threadId);
+    let body;
+    const card = extractCard(message);
+    if (card) {
+      body = cardToLinearMarkdown(card);
+    } else {
+      body = this.formatConverter.renderPostable(message);
+    }
+    body = convertEmojiPlaceholders(body, "linear");
+    const commentPayload = await this.linearClient.updateComment(messageId, {
+      body
+    });
+    const comment = await commentPayload.comment;
+    if (!comment) {
+      throw new Error("Failed to update comment on Linear");
+    }
+    return {
+      id: comment.id,
+      threadId,
+      raw: {
+        comment: {
+          id: comment.id,
+          body: comment.body,
+          issueId,
+          userId: this._botUserId || "",
+          createdAt: comment.createdAt.toISOString(),
+          updatedAt: comment.updatedAt.toISOString(),
+          url: comment.url
+        }
+      }
+    };
+  }
+  /**
+   * Delete a message (delete a comment).
+   *
+   * Uses LinearClient.deleteComment(id).
+   */
+  async deleteMessage(_threadId, messageId) {
+    await this.ensureValidToken();
+    await this.linearClient.deleteComment(messageId);
+  }
+  /**
+   * Add a reaction to a comment.
+   *
+   * Uses LinearClient.createReaction({ commentId, emoji }).
+   * Linear reactions use emoji strings (unicode).
+   */
+  async addReaction(_threadId, messageId, emoji) {
+    await this.ensureValidToken();
+    const emojiStr = this.resolveEmoji(emoji);
+    await this.linearClient.createReaction({
+      commentId: messageId,
+      emoji: emojiStr
+    });
+  }
+  /**
+   * 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.
+   */
+  async removeReaction(_threadId, _messageId, _emoji) {
+    this.logger.warn(
+      "removeReaction is not fully supported on Linear - reaction ID lookup would be required"
+    );
+  }
+  /**
+   * Start typing indicator. Not supported by Linear.
+   */
+  async startTyping(_threadId) {
+  }
+  /**
+   * 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).
+   */
+  async fetchMessages(threadId, options) {
+    await this.ensureValidToken();
+    const { issueId, commentId } = this.decodeThreadId(threadId);
+    if (commentId) {
+      return this.fetchCommentThread(threadId, issueId, commentId, options);
+    }
+    return this.fetchIssueComments(threadId, issueId, options);
+  }
+  /**
+   * Fetch top-level comments on an issue.
+   */
+  async fetchIssueComments(threadId, issueId, options) {
+    const issue = await this.linearClient.issue(issueId);
+    const commentsConnection = await issue.comments({
+      first: options?.limit ?? 50
+    });
+    const messages = await this.commentsToMessages(
+      commentsConnection.nodes,
+      threadId,
+      issueId
+    );
+    return {
+      messages,
+      nextCursor: commentsConnection.pageInfo.hasNextPage ? commentsConnection.pageInfo.endCursor : void 0
+    };
+  }
+  /**
+   * Fetch a comment thread (root comment + its children/replies).
+   */
+  async fetchCommentThread(threadId, issueId, commentId, options) {
+    const rootComment = await this.linearClient.comment({ id: commentId });
+    if (!rootComment) {
+      return { messages: [] };
+    }
+    const childrenConnection = await rootComment.children({
+      first: options?.limit ?? 50
+    });
+    const rootMessages = await this.commentsToMessages(
+      [rootComment],
+      threadId,
+      issueId
+    );
+    const childMessages = await this.commentsToMessages(
+      childrenConnection.nodes,
+      threadId,
+      issueId
+    );
+    return {
+      messages: [...rootMessages, ...childMessages],
+      nextCursor: childrenConnection.pageInfo.hasNextPage ? childrenConnection.pageInfo.endCursor : void 0
+    };
+  }
+  /**
+   * Convert an array of Linear SDK Comment objects to Message instances.
+   */
+  async commentsToMessages(comments, threadId, issueId) {
+    const messages = [];
+    for (const comment of comments) {
+      const user = await comment.user;
+      const author = {
+        userId: user?.id || "unknown",
+        userName: user?.displayName || "unknown",
+        fullName: user?.name || user?.displayName || "unknown",
+        isBot: false,
+        isMe: user?.id === this._botUserId
+      };
+      const formatted = this.formatConverter.toAst(
+        comment.body
+      );
+      messages.push(
+        new Message({
+          id: comment.id,
+          threadId,
+          text: comment.body,
+          formatted,
+          author,
+          metadata: {
+            dateSent: new Date(comment.createdAt),
+            edited: comment.createdAt.getTime() !== comment.updatedAt.getTime(),
+            editedAt: comment.createdAt.getTime() !== comment.updatedAt.getTime() ? new Date(comment.updatedAt) : void 0
+          },
+          attachments: [],
+          raw: {
+            comment: {
+              id: comment.id,
+              body: comment.body,
+              issueId,
+              userId: user?.id || "unknown",
+              createdAt: comment.createdAt.toISOString(),
+              updatedAt: comment.updatedAt.toISOString(),
+              url: comment.url
+            }
+          }
+        })
+      );
+    }
+    return messages;
+  }
+  /**
+   * Fetch thread info for a Linear issue.
+   */
+  async fetchThread(threadId) {
+    await this.ensureValidToken();
+    const { issueId } = this.decodeThreadId(threadId);
+    const issue = await this.linearClient.issue(issueId);
+    return {
+      id: threadId,
+      channelId: issueId,
+      channelName: `${issue.identifier}: ${issue.title}`,
+      isDM: false,
+      metadata: {
+        issueId,
+        identifier: issue.identifier,
+        title: issue.title,
+        url: issue.url
+      }
+    };
+  }
+  /**
+   * Encode a Linear thread ID.
+   *
+   * Formats:
+   * - Issue-level: linear:{issueId}
+   * - Comment thread: linear:{issueId}:c:{commentId}
+   */
+  encodeThreadId(platformData) {
+    if (platformData.commentId) {
+      return `linear:${platformData.issueId}:c:${platformData.commentId}`;
+    }
+    return `linear:${platformData.issueId}`;
+  }
+  /**
+   * Decode a Linear thread ID.
+   *
+   * Formats:
+   * - Issue-level: linear:{issueId}
+   * - Comment thread: linear:{issueId}:c:{commentId}
+   */
+  decodeThreadId(threadId) {
+    if (!threadId.startsWith("linear:")) {
+      throw new ValidationError(
+        "linear",
+        `Invalid Linear thread ID: ${threadId}`
+      );
+    }
+    const withoutPrefix = threadId.slice(7);
+    if (!withoutPrefix) {
+      throw new ValidationError(
+        "linear",
+        `Invalid Linear thread ID format: ${threadId}`
+      );
+    }
+    const commentMatch = withoutPrefix.match(/^([^:]+):c:([^:]+)$/);
+    if (commentMatch) {
+      return {
+        issueId: commentMatch[1],
+        commentId: commentMatch[2]
+      };
+    }
+    return { issueId: withoutPrefix };
+  }
+  /**
+   * Parse platform message format to normalized format.
+   */
+  parseMessage(raw) {
+    const text = raw.comment.body || "";
+    const formatted = this.formatConverter.toAst(text);
+    return new Message({
+      id: raw.comment.id,
+      threadId: "",
+      text,
+      formatted,
+      author: {
+        userId: raw.comment.userId,
+        userName: "unknown",
+        fullName: "unknown",
+        isBot: false,
+        isMe: raw.comment.userId === this._botUserId
+      },
+      metadata: {
+        dateSent: raw.comment.createdAt ? new Date(raw.comment.createdAt) : /* @__PURE__ */ new Date(),
+        edited: raw.comment.createdAt !== raw.comment.updatedAt,
+        editedAt: raw.comment.createdAt !== raw.comment.updatedAt && raw.comment.updatedAt ? new Date(raw.comment.updatedAt) : void 0
+      },
+      attachments: [],
+      raw
+    });
+  }
+  /**
+   * Render formatted content to Linear markdown.
+   */
+  renderFormatted(content) {
+    return this.formatConverter.fromAst(content);
+  }
+  /**
+   * Resolve an emoji value to a unicode string.
+   * Linear uses standard unicode emoji for reactions.
+   */
+  resolveEmoji(emoji) {
+    const emojiName = typeof emoji === "string" ? emoji : emoji.name;
+    const mapping = {
+      thumbs_up: "\u{1F44D}",
+      thumbs_down: "\u{1F44E}",
+      heart: "\u2764\uFE0F",
+      fire: "\u{1F525}",
+      rocket: "\u{1F680}",
+      eyes: "\u{1F440}",
+      check: "\u2705",
+      warning: "\u26A0\uFE0F",
+      sparkles: "\u2728",
+      wave: "\u{1F44B}",
+      raised_hands: "\u{1F64C}",
+      laugh: "\u{1F604}",
+      hooray: "\u{1F389}",
+      confused: "\u{1F615}"
+    };
+    return mapping[emojiName] || emojiName;
+  }
+};
+function createLinearAdapter(config) {
+  return new LinearAdapter(config);
+}
+export {
+  LinearAdapter,
+  createLinearAdapter
+};
+//# sourceMappingURL=index.js.map