@chat-adapter/github 0.0.1

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,255 @@
+# @chat-adapter/github
+
+GitHub adapter for the [chat](https://github.com/vercel-labs/chat) SDK. Enables bots to respond to @mentions in GitHub PR comment threads.
+
+## Installation
+
+```bash
+npm install chat @chat-adapter/github
+```
+
+## Usage
+
+```typescript
+import { Chat } from "chat";
+import { createGitHubAdapter } from "@chat-adapter/github";
+import { MemoryState } from "@chat-adapter/state-memory";
+
+const chat = new Chat({
+  userName: "my-bot",
+  adapters: {
+    github: createGitHubAdapter({
+      token: process.env.GITHUB_TOKEN!,
+      webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+      userName: "my-bot",
+      logger: console,
+    }),
+  },
+  state: new MemoryState(),
+  logger: "info",
+});
+
+// Handle @mentions in PR comments
+chat.onNewMention(async (thread, message) => {
+  await thread.post("Hello from GitHub!");
+});
+```
+
+## Configuration
+
+| Option           | Required | Description                                                                                                                                                    |
+| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token`          | Yes\*    | [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with `repo` scope |
+| `appId`          | Yes\*    | [GitHub App](https://docs.github.com/en/apps/creating-github-apps) ID                                                                                          |
+| `privateKey`     | For Apps | GitHub App private key (PEM format)                                                                                                                            |
+| `installationId` | No       | Installation ID (omit for multi-tenant)                                                                                                                        |
+| `webhookSecret`  | Yes      | [Webhook secret](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) for signature verification                                  |
+| `userName`       | Yes      | Bot username for @mention detection                                                                                                                            |
+| `botUserId`      | No       | Bot's numeric user ID (auto-detected if not provided)                                                                                                          |
+
+\*Either `token` or `appId`/`privateKey` is required.
+
+## Environment Variables
+
+```bash
+# Personal Access Token auth
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+
+# OR GitHub App auth
+GITHUB_APP_ID=123456
+GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----..."
+GITHUB_INSTALLATION_ID=12345678  # Optional for multi-tenant apps
+
+# Webhook secret (required)
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+```
+
+## GitHub Setup
+
+### Option A: Personal Access Token (PAT)
+
+Best for personal projects, testing, or simple single-repo bots.
+
+1. Go to [Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
+2. Create a new token with `repo` scope
+3. Set `GITHUB_TOKEN` environment variable
+
+### Option B: GitHub App (Recommended)
+
+Better rate limits, security, and supports multiple installations.
+
+#### 1. Create the App
+
+1. Go to [Settings → Developer settings → GitHub Apps → New GitHub App](https://github.com/settings/apps/new)
+2. Fill in:
+   - **Name**: Your bot's name
+   - **Homepage URL**: Your app's website
+   - **Webhook URL**: `https://your-domain.com/api/webhooks/github`
+   - **Webhook secret**: Generate a secure secret
+3. Set **Permissions**:
+   - Repository -> Issues: Read & write
+   - Repository -> Pull requests: Read & write
+   - Repository -> Metadata: Read-only
+4. Subscribe to **events**:
+   - Issue comment
+   - Pull request review comment
+5. Under "Where can this GitHub App be installed?":
+   - **Only on this account** - For private/testing apps
+   - **Any account** - For public apps others can install
+6. Click **"Create GitHub App"**
+7. Note your **App ID** from the app settings page (shown at the top)
+8. Scroll down and click **"Generate a private key"** - save the downloaded `.pem` file
+
+#### 2. Install the App
+
+1. After creating the app, go to your app's settings page
+2. Click **"Install App"** in the left sidebar
+3. Click **"Install"** next to your organization or account
+4. Choose which repositories to grant access:
+   - **All repositories** - App can access all current and future repos
+   - **Only select repositories** - Pick specific repos (recommended for testing)
+5. Click **"Install"**
+6. Note the **Installation ID** from the URL after installation:
+   ```
+   https://github.com/settings/installations/12345678
+                                              ^^^^^^^^
+                                              This is your Installation ID
+   ```
+
+#### 3. Configure the Adapter
+
+**Single-tenant (fixed installation):**
+
+```typescript
+createGitHubAdapter({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  installationId: parseInt(process.env.GITHUB_INSTALLATION_ID!),
+  webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+  userName: "my-bot[bot]",
+  logger: console,
+});
+```
+
+**Multi-tenant (public app anyone can install):**
+
+Simply omit `installationId`. The adapter automatically extracts it from webhooks and caches API clients per-installation:
+
+```typescript
+import { Chat } from "chat";
+import { createGitHubAdapter } from "@chat-adapter/github";
+import { RedisState } from "@chat-adapter/state-redis";
+
+const chat = new Chat({
+  userName: "my-bot[bot]",
+  adapters: {
+    github: createGitHubAdapter({
+      appId: process.env.GITHUB_APP_ID!,
+      privateKey: process.env.GITHUB_PRIVATE_KEY!,
+      // No installationId - handled automatically!
+      webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+      userName: "my-bot[bot]",
+      logger: console,
+    }),
+  },
+  // Use Redis to persist installation mappings
+  state: new RedisState({ url: process.env.REDIS_URL! }),
+  logger: "info",
+});
+```
+
+### Webhook Setup
+
+See the [GitHub Webhooks documentation](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks) for detailed instructions.
+
+**For repository/org webhooks:**
+
+1. Go to repository/org **Settings → Webhooks → Add webhook**
+2. Set **Payload URL** to `https://your-domain.com/api/webhooks/github`
+3. Set **Content type** to `application/json` (**required** - the default `application/x-www-form-urlencoded` will not work)
+4. Set **Secret** to match your `webhookSecret`
+5. Select events:
+   - [Issue comments](https://docs.github.com/en/webhooks/webhook-events-and-payloads#issue_comment) (PR-level)
+   - [Pull request review comments](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request_review_comment) (line-specific)
+
+**For GitHub Apps:** Webhooks are configured during app creation. Make sure to select `application/json` as the content type.
+
+## Features
+
+- Message posting and editing
+- Message deletion
+- [Reaction handling](https://docs.github.com/en/rest/reactions) (add/remove)
+- PR-level comments (Conversation tab)
+- Review comment threads (Files Changed tab - line-specific)
+- Cards (rendered as [GitHub Flavored Markdown](https://github.github.com/gfm/))
+- Multi-tenant support (automatic installation ID handling)
+
+## Thread Model
+
+GitHub has two types of comment threads:
+
+| Type            | Tab           | API                                                                  | Thread ID Format                                  |
+| --------------- | ------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
+| PR-level        | Conversation  | [Issue Comments](https://docs.github.com/en/rest/issues/comments)    | `github:{owner}/{repo}:{prNumber}`                |
+| Review comments | Files Changed | [PR Review Comments](https://docs.github.com/en/rest/pulls/comments) | `github:{owner}/{repo}:{prNumber}:rc:{commentId}` |
+
+Example thread IDs:
+
+- `github:acme/app:123` (PR-level)
+- `github:acme/app:123:rc:456789` (line-specific review comment)
+
+## Reactions
+
+Supports [GitHub's reaction emoji](https://docs.github.com/en/rest/reactions/reactions#about-reactions):
+
+| SDK Emoji     | GitHub Reaction |
+| ------------- | --------------- |
+| `thumbs_up`   | 👍 (+1)         |
+| `thumbs_down` | 👎 (-1)         |
+| `laugh`       | 😄              |
+| `confused`    | 😕              |
+| `heart`       | ❤️              |
+| `hooray`      | 🎉              |
+| `rocket`      | 🚀              |
+| `eyes`        | 👀              |
+
+## Limitations
+
+- **No typing indicators** - GitHub doesn't support typing indicators
+- **No streaming** - Messages posted in full (editing supported for updates)
+- **No DMs** - GitHub doesn't have direct messages
+- **No modals** - GitHub doesn't support interactive modals
+- **Action buttons** - Rendered as text; use link buttons for clickable actions
+
+## Troubleshooting
+
+### "Invalid signature" error
+
+- Verify `GITHUB_WEBHOOK_SECRET` matches your webhook configuration
+- Ensure the request body isn't being modified before verification
+
+### "Invalid JSON" error
+
+- Change webhook **Content type** to `application/json` (GitHub defaults to `application/x-www-form-urlencoded` which doesn't work)
+
+### Bot not responding to mentions
+
+- Verify webhook events are configured (issue_comment, pull_request_review_comment)
+- Check that the webhook URL is correct and accessible
+- Ensure the bot has been installed on the repository
+- Verify the `userName` config matches your bot's GitHub username
+
+### "Installation ID required" error
+
+- This occurs when making API calls outside webhook context in multi-tenant mode
+- Ensure you're using a persistent state adapter (Redis) to store installation mappings
+- The first interaction must come from a webhook to establish the mapping
+
+### Rate limiting
+
+- [PATs have lower rate limits](https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api) than GitHub Apps
+- Consider switching to a GitHub App for production use
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,377 @@
+import { Logger, Adapter, ChatInstance, WebhookOptions, AdapterPostableMessage, RawMessage, EmojiValue, FetchOptions, FetchResult, ThreadInfo, Message, FormattedContent } from 'chat';
+
+/**
+ * Type definitions for the GitHub adapter.
+ */
+
+/**
+ * Base configuration options shared by all auth methods.
+ */
+interface GitHubAdapterBaseConfig {
+    /** Logger instance for error reporting */
+    logger: Logger;
+    /**
+     * Webhook secret for HMAC-SHA256 verification.
+     * Set this in your GitHub webhook settings.
+     */
+    webhookSecret: string;
+    /**
+     * Bot username (e.g., "my-bot" or "my-bot[bot]" for GitHub Apps).
+     * Used for @-mention detection.
+     */
+    userName: string;
+    /**
+     * Bot's GitHub user ID (numeric).
+     * Used for self-message detection. If not provided, will be fetched on first API call.
+     */
+    botUserId?: number;
+}
+/**
+ * Configuration using a Personal Access Token (PAT).
+ * Simpler setup, suitable for personal bots or testing.
+ */
+interface GitHubAdapterPATConfig extends GitHubAdapterBaseConfig {
+    /** Personal Access Token with appropriate scopes (repo, write:discussion) */
+    token: string;
+    appId?: never;
+    privateKey?: never;
+    installationId?: never;
+}
+/**
+ * Configuration using a GitHub App with a fixed installation.
+ * Use this when your bot is only installed on a single org/repo.
+ */
+interface GitHubAdapterAppConfig extends GitHubAdapterBaseConfig {
+    /** GitHub App ID */
+    appId: string;
+    /** GitHub App private key (PEM format) */
+    privateKey: string;
+    /** Installation ID for the app (for single-tenant apps) */
+    installationId: number;
+    token?: never;
+}
+/**
+ * Configuration using a GitHub App for multi-tenant (public) apps.
+ * The installation ID is automatically extracted from each webhook payload.
+ * Use this when your bot can be installed by anyone.
+ */
+interface GitHubAdapterMultiTenantAppConfig extends GitHubAdapterBaseConfig {
+    /** GitHub App ID */
+    appId: string;
+    /** GitHub App private key (PEM format) */
+    privateKey: string;
+    /** Omit installationId to enable multi-tenant mode */
+    installationId?: never;
+    token?: never;
+}
+/**
+ * GitHub adapter configuration - PAT, single-tenant App, or multi-tenant App.
+ */
+type GitHubAdapterConfig = GitHubAdapterPATConfig | GitHubAdapterAppConfig | GitHubAdapterMultiTenantAppConfig;
+/**
+ * Decoded thread ID for GitHub.
+ *
+ * Thread types:
+ * - PR-level: Comments in the "Conversation" tab (issue_comment API)
+ * - Review comment: Line-specific comments in "Files changed" tab (pull request review comment API)
+ */
+interface GitHubThreadId {
+    /** Repository owner (user or organization) */
+    owner: string;
+    /** Repository name */
+    repo: string;
+    /** Pull request number */
+    prNumber: number;
+    /**
+     * Root review comment ID for line-specific threads.
+     * If present, this is a review comment thread.
+     * If absent, this is a PR-level (issue comment) thread.
+     */
+    reviewCommentId?: number;
+}
+/**
+ * GitHub user object (simplified).
+ */
+interface GitHubUser {
+    id: number;
+    login: string;
+    avatar_url?: string;
+    type: "User" | "Bot" | "Organization";
+}
+/**
+ * GitHub repository object (simplified).
+ */
+interface GitHubRepository {
+    id: number;
+    name: string;
+    full_name: string;
+    owner: GitHubUser;
+}
+/**
+ * GitHub issue comment (PR-level comment in Conversation tab).
+ */
+interface GitHubIssueComment {
+    id: number;
+    body: string;
+    user: GitHubUser;
+    created_at: string;
+    updated_at: string;
+    html_url: string;
+    /** Reactions summary */
+    reactions?: {
+        url: string;
+        total_count: number;
+        "+1": number;
+        "-1": number;
+        laugh: number;
+        hooray: number;
+        confused: number;
+        heart: number;
+        rocket: number;
+        eyes: number;
+    };
+}
+/**
+ * GitHub pull request review comment (line-specific comment in Files Changed tab).
+ */
+interface GitHubReviewComment {
+    id: number;
+    body: string;
+    user: GitHubUser;
+    created_at: string;
+    updated_at: string;
+    html_url: string;
+    /** The commit SHA the comment is associated with */
+    commit_id: string;
+    /** The original commit SHA (for outdated comments) */
+    original_commit_id: string;
+    /** The diff hunk the comment applies to */
+    diff_hunk: string;
+    /** Path to the file being commented on */
+    path: string;
+    /** Line number in the diff */
+    line?: number;
+    /** Original line number */
+    original_line?: number;
+    /** Side of the diff (LEFT or RIGHT) */
+    side?: "LEFT" | "RIGHT";
+    /** Start line for multi-line comments */
+    start_line?: number | null;
+    /** Start side for multi-line comments */
+    start_side?: "LEFT" | "RIGHT" | null;
+    /**
+     * The ID of the comment this is a reply to.
+     * If present, this is a reply in an existing thread.
+     * If absent, this is the root of a new thread.
+     */
+    in_reply_to_id?: number;
+    /** Reactions summary */
+    reactions?: GitHubIssueComment["reactions"];
+}
+/**
+ * Platform-specific raw message type for GitHub.
+ * Can be either an issue comment or a review comment.
+ */
+type GitHubRawMessage = {
+    type: "issue_comment";
+    comment: GitHubIssueComment;
+    repository: GitHubRepository;
+    prNumber: number;
+} | {
+    type: "review_comment";
+    comment: GitHubReviewComment;
+    repository: GitHubRepository;
+    prNumber: number;
+};
+
+/**
+ * GitHub adapter for chat SDK.
+ *
+ * Supports both PR-level comments (Conversation tab) and review comment threads
+ * (Files Changed tab - line-specific).
+ *
+ * @example Single-tenant (your own org)
+ * ```typescript
+ * import { Chat } from "chat";
+ * import { GitHubAdapter } from "@chat-adapter/github";
+ * import { MemoryState } from "@chat-adapter/state-memory";
+ *
+ * const chat = new Chat({
+ *   userName: "my-bot",
+ *   adapters: {
+ *     github: new GitHubAdapter({
+ *       token: process.env.GITHUB_TOKEN!,
+ *       webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+ *       userName: "my-bot",
+ *       logger: console,
+ *     }),
+ *   },
+ *   state: new MemoryState(),
+ *   logger: "info",
+ * });
+ * ```
+ *
+ * @example Multi-tenant (public app anyone can install)
+ * ```typescript
+ * const chat = new Chat({
+ *   userName: "my-bot[bot]",
+ *   adapters: {
+ *     github: new GitHubAdapter({
+ *       appId: process.env.GITHUB_APP_ID!,
+ *       privateKey: process.env.GITHUB_PRIVATE_KEY!,
+ *       // No installationId - automatically extracted from webhooks
+ *       webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+ *       userName: "my-bot[bot]",
+ *       logger: console,
+ *     }),
+ *   },
+ *   state: new MemoryState(),
+ *   logger: "info",
+ * });
+ * ```
+ */
+declare class GitHubAdapter implements Adapter<GitHubThreadId, GitHubRawMessage> {
+    readonly name = "github";
+    readonly userName: string;
+    private octokit;
+    private appCredentials;
+    private installationClients;
+    private webhookSecret;
+    private chat;
+    private logger;
+    private _botUserId;
+    private formatConverter;
+    /** Bot user ID (numeric) used for self-message detection */
+    get botUserId(): string | undefined;
+    /** Whether this adapter is in multi-tenant mode (no fixed installation ID) */
+    get isMultiTenant(): boolean;
+    constructor(config: GitHubAdapterConfig);
+    /**
+     * Get or create an Octokit instance for a specific installation.
+     * For single-tenant mode, returns the single instance.
+     * For multi-tenant mode, creates/caches instances per installation.
+     */
+    private getOctokit;
+    initialize(chat: ChatInstance): Promise<void>;
+    /**
+     * Get the state key for storing installation ID for a repository.
+     */
+    private getInstallationKey;
+    /**
+     * Store the installation ID for a repository (for multi-tenant mode).
+     */
+    private storeInstallationId;
+    /**
+     * Get the installation ID for a repository (for multi-tenant mode).
+     */
+    private getInstallationId;
+    /**
+     * Handle incoming webhook from GitHub.
+     */
+    handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
+    /**
+     * Verify GitHub webhook signature using HMAC-SHA256.
+     */
+    private verifySignature;
+    /**
+     * Handle issue_comment webhook (PR-level comments in Conversation tab).
+     */
+    private handleIssueComment;
+    /**
+     * Handle pull_request_review_comment webhook (line-specific comments).
+     */
+    private handleReviewComment;
+    /**
+     * Parse an issue comment into a normalized Message.
+     */
+    private parseIssueComment;
+    /**
+     * Parse a review comment into a normalized Message.
+     */
+    private parseReviewComment;
+    /**
+     * Parse a GitHub user into an Author.
+     */
+    private parseAuthor;
+    /**
+     * Get the Octokit client for a specific thread.
+     * In multi-tenant mode, looks up the installation ID from state.
+     */
+    private getOctokitForThread;
+    /**
+     * Post a message to a thread.
+     */
+    postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<GitHubRawMessage>>;
+    /**
+     * Edit an existing message.
+     */
+    editMessage(threadId: string, messageId: string, message: AdapterPostableMessage): Promise<RawMessage<GitHubRawMessage>>;
+    /**
+     * Delete a message.
+     */
+    deleteMessage(threadId: string, messageId: string): Promise<void>;
+    /**
+     * Add a reaction to a message.
+     */
+    addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Remove a reaction from a message.
+     */
+    removeReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
+    /**
+     * Convert SDK emoji to GitHub reaction content.
+     */
+    private emojiToGitHubReaction;
+    /**
+     * Show typing indicator (no-op for GitHub).
+     */
+    startTyping(_threadId: string): Promise<void>;
+    /**
+     * Fetch messages from a thread.
+     */
+    fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<GitHubRawMessage>>;
+    /**
+     * Fetch thread metadata.
+     */
+    fetchThread(threadId: string): Promise<ThreadInfo>;
+    /**
+     * Encode platform data into a thread ID string.
+     *
+     * Thread ID formats:
+     * - PR-level: `github:{owner}/{repo}:{prNumber}`
+     * - Review comment: `github:{owner}/{repo}:{prNumber}:rc:{reviewCommentId}`
+     */
+    encodeThreadId(platformData: GitHubThreadId): string;
+    /**
+     * Decode thread ID string back to platform data.
+     */
+    decodeThreadId(threadId: string): GitHubThreadId;
+    /**
+     * Parse a raw message into normalized format.
+     */
+    parseMessage(raw: GitHubRawMessage): Message<GitHubRawMessage>;
+    /**
+     * Render formatted content to GitHub markdown.
+     */
+    renderFormatted(content: FormattedContent): string;
+}
+/**
+ * Create a new GitHub adapter instance.
+ *
+ * @example
+ * ```typescript
+ * const chat = new Chat({
+ *   adapters: {
+ *     github: createGitHubAdapter({
+ *       token: process.env.GITHUB_TOKEN!,
+ *       webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+ *       userName: "my-bot",
+ *       logger: console,
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function createGitHubAdapter(config: GitHubAdapterConfig): GitHubAdapter;
+
+export { GitHubAdapter, type GitHubAdapterAppConfig, type GitHubAdapterConfig, type GitHubAdapterMultiTenantAppConfig, type GitHubAdapterPATConfig, type GitHubRawMessage, type GitHubThreadId, createGitHubAdapter };