claude-threads 0.13.0 → 0.14.1

package/dist/platform/client.d.ts

@@ -0,0 +1,140 @@
+import { EventEmitter } from 'events';
+import type { PlatformUser, PlatformPost, PlatformReaction, PlatformFile } from './types.js';
+import type { PlatformFormatter } from './formatter.js';
+/**
+ * Events emitted by PlatformClient
+ */
+export interface PlatformClientEvents {
+    connected: () => void;
+    disconnected: () => void;
+    error: (error: Error) => void;
+    message: (post: PlatformPost, user: PlatformUser | null) => void;
+    reaction: (reaction: PlatformReaction, user: PlatformUser | null) => void;
+}
+/**
+ * Platform-agnostic client interface
+ *
+ * All platform implementations (Mattermost, Slack) must implement this interface.
+ * This allows SessionManager and other code to work with any platform without
+ * knowing the specific implementation details.
+ */
+export interface PlatformClient extends EventEmitter {
+    /**
+     * Unique identifier for this platform instance
+     * e.g., 'mattermost-internal', 'slack-eng'
+     */
+    readonly platformId: string;
+    /**
+     * Platform type
+     * e.g., 'mattermost', 'slack'
+     */
+    readonly platformType: string;
+    /**
+     * Human-readable display name
+     * e.g., 'Internal Team', 'Engineering Slack'
+     */
+    readonly displayName: string;
+    /**
+     * Connect to the platform (WebSocket, Socket Mode, etc.)
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the platform
+     */
+    disconnect(): void;
+    /**
+     * Get the bot's own user info
+     */
+    getBotUser(): Promise<PlatformUser>;
+    /**
+     * Get a user by their ID
+     */
+    getUser(userId: string): Promise<PlatformUser | null>;
+    /**
+     * Check if a username is in the allowed users list
+     */
+    isUserAllowed(username: string): boolean;
+    /**
+     * Get the bot's mention name (e.g., 'claude-code')
+     */
+    getBotName(): string;
+    /**
+     * Get platform config for MCP permission server
+     */
+    getMcpConfig(): {
+        type: string;
+        url: string;
+        token: string;
+        channelId: string;
+        allowedUsers: string[];
+    };
+    /**
+     * Get the platform-specific markdown formatter
+     * Use this to format bold, code, etc. in a platform-appropriate way.
+     */
+    getFormatter(): PlatformFormatter;
+    /**
+     * Create a new post/message
+     * @param message - Message text
+     * @param threadId - Optional thread parent ID
+     * @returns The created post
+     */
+    createPost(message: string, threadId?: string): Promise<PlatformPost>;
+    /**
+     * Update an existing post/message
+     * @param postId - Post ID to update
+     * @param message - New message text
+     * @returns The updated post
+     */
+    updatePost(postId: string, message: string): Promise<PlatformPost>;
+    /**
+     * Create a post with reaction options (for interactive prompts)
+     * @param message - Message text
+     * @param reactions - Array of emoji names to add as options
+     * @param threadId - Optional thread parent ID
+     * @returns The created post
+     */
+    createInteractivePost(message: string, reactions: string[], threadId?: string): Promise<PlatformPost>;
+    /**
+     * Get a post by ID
+     * @param postId - Post ID
+     * @returns The post, or null if not found/deleted
+     */
+    getPost(postId: string): Promise<PlatformPost | null>;
+    /**
+     * Add a reaction to a post
+     * @param postId - Post ID
+     * @param emojiName - Emoji name (e.g., '+1', 'white_check_mark')
+     */
+    addReaction(postId: string, emojiName: string): Promise<void>;
+    /**
+     * Check if a message mentions the bot
+     * @param message - Message text
+     */
+    isBotMentioned(message: string): boolean;
+    /**
+     * Extract the prompt from a message (remove bot mention)
+     * @param message - Message text
+     * @returns The message with bot mention removed
+     */
+    extractPrompt(message: string): string;
+    /**
+     * Send typing indicator to show bot is "thinking"
+     * @param threadId - Optional thread ID
+     */
+    sendTyping(threadId?: string): void;
+    /**
+     * Download a file attachment
+     * @param fileId - File ID
+     * @returns File contents as Buffer
+     */
+    downloadFile?(fileId: string): Promise<Buffer>;
+    /**
+     * Get file metadata
+     * @param fileId - File ID
+     * @returns File metadata
+     */
+    getFileInfo?(fileId: string): Promise<PlatformFile>;
+    on<K extends keyof PlatformClientEvents>(event: K, listener: PlatformClientEvents[K]): this;
+    emit<K extends keyof PlatformClientEvents>(event: K, ...args: Parameters<PlatformClientEvents[K]>): boolean;
+}

package/dist/platform/formatter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Platform-agnostic markdown formatter interface
+ *
+ * Different platforms have slightly different markdown dialects:
+ * - Mattermost: Standard markdown (**bold**, _italic_, @username)
+ * - Slack: mrkdwn (*bold*, _italic_, <@U123> for mentions)
+ *
+ * This interface abstracts those differences.
+ */
+export interface PlatformFormatter {
+    /**
+     * Format text as bold
+     * Mattermost: **text**
+     * Slack: *text*
+     */
+    formatBold(text: string): string;
+    /**
+     * Format text as italic
+     * Mattermost: _text_ or *text*
+     * Slack: _text_
+     */
+    formatItalic(text: string): string;
+    /**
+     * Format text as inline code
+     * Both: `code`
+     */
+    formatCode(text: string): string;
+    /**
+     * Format text as code block with optional language
+     * Both: ```lang\ncode\n```
+     */
+    formatCodeBlock(code: string, language?: string): string;
+    /**
+     * Format a user mention
+     * Mattermost: @username
+     * Slack: <@U123456> (requires user ID)
+     */
+    formatUserMention(username: string, userId?: string): string;
+    /**
+     * Format a hyperlink
+     * Mattermost: [text](url)
+     * Slack: <url|text>
+     */
+    formatLink(text: string, url: string): string;
+    /**
+     * Format a bulleted list item
+     * Both: - item or * item
+     */
+    formatListItem(text: string): string;
+    /**
+     * Format a numbered list item
+     * Both: 1. item
+     */
+    formatNumberedListItem(number: number, text: string): string;
+    /**
+     * Format a blockquote
+     * Both: > text
+     */
+    formatBlockquote(text: string): string;
+    /**
+     * Format a horizontal rule
+     * Both: ---
+     */
+    formatHorizontalRule(): string;
+    /**
+     * Format a heading
+     * Both: # Heading (level 1), ## Heading (level 2), etc.
+     */
+    formatHeading(text: string, level: number): string;
+    /**
+     * Escape special characters in text to prevent formatting
+     */
+    escapeText(text: string): string;
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Platform abstraction layer
+ *
+ * This module provides platform-agnostic interfaces and types that allow
+ * claude-threads to work with multiple chat platforms (Mattermost, Slack, etc.)
+ * without coupling the core logic to any specific platform.
+ */
+export type { PlatformClient, PlatformClientEvents } from './client.js';
+export type { PlatformFormatter } from './formatter.js';
+export type { PermissionApi, PermissionApiConfig, ReactionEvent, PostedMessage, } from './permission-api.js';
+export type { PlatformUser, PlatformPost, PlatformReaction, PlatformFile, CreatePostRequest, UpdatePostRequest, AddReactionRequest, } from './types.js';

package/dist/platform/index.js

@@ -0,0 +1,8 @@
+/**
+ * Platform abstraction layer
+ *
+ * This module provides platform-agnostic interfaces and types that allow
+ * claude-threads to work with multiple chat platforms (Mattermost, Slack, etc.)
+ * without coupling the core logic to any specific platform.
+ */
+export {};

package/dist/platform/mattermost/client.d.ts

@@ -0,0 +1,70 @@
+import { EventEmitter } from 'events';
+import type { MattermostPlatformConfig } from '../../config/migration.js';
+import type { PlatformClient, PlatformUser, PlatformPost, PlatformFile } from '../index.js';
+import type { PlatformFormatter } from '../formatter.js';
+export declare class MattermostClient extends EventEmitter implements PlatformClient {
+    readonly platformId: string;
+    readonly platformType: "mattermost";
+    readonly displayName: string;
+    private ws;
+    private url;
+    private token;
+    private channelId;
+    private botName;
+    private allowedUsers;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private userCache;
+    private botUserId;
+    private readonly formatter;
+    private pingInterval;
+    private lastMessageAt;
+    private readonly PING_INTERVAL_MS;
+    private readonly PING_TIMEOUT_MS;
+    constructor(platformConfig: MattermostPlatformConfig);
+    private normalizePlatformUser;
+    private normalizePlatformPost;
+    private normalizePlatformReaction;
+    private normalizePlatformFile;
+    private api;
+    getBotUser(): Promise<PlatformUser>;
+    getUser(userId: string): Promise<PlatformUser | null>;
+    createPost(message: string, threadId?: string): Promise<PlatformPost>;
+    updatePost(postId: string, message: string): Promise<PlatformPost>;
+    addReaction(postId: string, emojiName: string): Promise<void>;
+    /**
+     * Create a post with reaction options for user interaction
+     *
+     * This is a common pattern for interactive posts that need user response
+     * via reactions (e.g., approval prompts, questions, permission requests).
+     *
+     * @param message - Post message content
+     * @param reactions - Array of emoji names to add as reaction options
+     * @param threadId - Optional thread root ID
+     * @returns The created post
+     */
+    createInteractivePost(message: string, reactions: string[], threadId?: string): Promise<PlatformPost>;
+    downloadFile(fileId: string): Promise<Buffer>;
+    getFileInfo(fileId: string): Promise<PlatformFile>;
+    getPost(postId: string): Promise<PlatformPost | null>;
+    connect(): Promise<void>;
+    private handleEvent;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    isUserAllowed(username: string): boolean;
+    isBotMentioned(message: string): boolean;
+    extractPrompt(message: string): string;
+    getBotName(): string;
+    getMcpConfig(): {
+        type: string;
+        url: string;
+        token: string;
+        channelId: string;
+        allowedUsers: string[];
+    };
+    getFormatter(): PlatformFormatter;
+    sendTyping(parentId?: string): void;
+    disconnect(): void;
+}

package/dist/{mattermost → platform/mattermost}/client.js

@@ -1,34 +1,96 @@
 import WebSocket from 'ws';
 import { EventEmitter } from 'events';
-import { wsLogger } from '../utils/logger.js';
+import { wsLogger } from '../../utils/logger.js';
+import { MattermostFormatter } from './formatter.js';
 // Escape special regex characters to prevent regex injection
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 export class MattermostClient extends EventEmitter {
+    // Platform identity (required by PlatformClient)
+    platformId;
+    platformType = 'mattermost';
+    displayName;
     ws = null;
-    config;
+    url;
+    token;
+    channelId;
+    botName;
+    allowedUsers;
     reconnectAttempts = 0;
     maxReconnectAttempts = 10;
     reconnectDelay = 1000;
     userCache = new Map();
     botUserId = null;
+    formatter = new MattermostFormatter();
     // Heartbeat to detect dead connections
     pingInterval = null;
     lastMessageAt = Date.now();
     PING_INTERVAL_MS = 30000; // Send ping every 30s
     PING_TIMEOUT_MS = 60000; // Reconnect if no message for 60s
-    constructor(config) {
+    constructor(platformConfig) {
         super();
-        this.config = config;
+        this.platformId = platformConfig.id;
+        this.displayName = platformConfig.displayName;
+        this.url = platformConfig.url;
+        this.token = platformConfig.token;
+        this.channelId = platformConfig.channelId;
+        this.botName = platformConfig.botName;
+        this.allowedUsers = platformConfig.allowedUsers;
+    }
+    // ============================================================================
+    // Type Normalization (Mattermost → Platform)
+    // ============================================================================
+    normalizePlatformUser(mattermostUser) {
+        return {
+            id: mattermostUser.id,
+            username: mattermostUser.username,
+            email: mattermostUser.email,
+        };
+    }
+    normalizePlatformPost(mattermostPost) {
+        // Normalize metadata.files if present
+        const metadata = mattermostPost.metadata
+            ? {
+                ...mattermostPost.metadata,
+                files: mattermostPost.metadata.files?.map((f) => this.normalizePlatformFile(f)),
+            }
+            : undefined;
+        return {
+            id: mattermostPost.id,
+            platformId: this.platformId,
+            channelId: mattermostPost.channel_id,
+            userId: mattermostPost.user_id,
+            message: mattermostPost.message,
+            rootId: mattermostPost.root_id,
+            createAt: mattermostPost.create_at,
+            metadata,
+        };
+    }
+    normalizePlatformReaction(mattermostReaction) {
+        return {
+            userId: mattermostReaction.user_id,
+            postId: mattermostReaction.post_id,
+            emojiName: mattermostReaction.emoji_name,
+            createAt: mattermostReaction.create_at,
+        };
+    }
+    normalizePlatformFile(mattermostFile) {
+        return {
+            id: mattermostFile.id,
+            name: mattermostFile.name,
+            size: mattermostFile.size,
+            mimeType: mattermostFile.mime_type,
+            extension: mattermostFile.extension,
+        };
     }
     // REST API helper
     async api(method, path, body) {
-        const url = `${this.config.mattermost.url}/api/v4${path}`;
+        const url = `${this.url}/api/v4${path}`;
         const response = await fetch(url, {
             method,
             headers: {
-                Authorization: `Bearer ${this.config.mattermost.token}`,
+                Authorization: `Bearer ${this.token}`,
                 'Content-Type': 'application/json',
             },
             body: body ? JSON.stringify(body) : undefined,
@@ -43,17 +105,18 @@ export class MattermostClient extends EventEmitter {
     async getBotUser() {
         const user = await this.api('GET', '/users/me');
         this.botUserId = user.id;
-        return user;
+        return this.normalizePlatformUser(user);
     }
     // Get user by ID (cached)
     async getUser(userId) {
-        if (this.userCache.has(userId)) {
-            return this.userCache.get(userId);
+        const cached = this.userCache.get(userId);
+        if (cached) {
+            return this.normalizePlatformUser(cached);
         }
         try {
             const user = await this.api('GET', `/users/${userId}`);
             this.userCache.set(userId, user);
-            return user;
+            return this.normalizePlatformUser(user);
         }
         catch {
             return null;
@@ -62,11 +125,12 @@ export class MattermostClient extends EventEmitter {
     // Post a message
     async createPost(message, threadId) {
         const request = {
-            channel_id: this.config.mattermost.channelId,
+            channel_id: this.channelId,
             message,
             root_id: threadId,
         };
-        return this.api('POST', '/posts', request);
+        const post = await this.api('POST', '/posts', request);
+        return this.normalizePlatformPost(post);
     }
     // Update a message (for streaming updates)
     async updatePost(postId, message) {
@@ -74,7 +138,8 @@ export class MattermostClient extends EventEmitter {
             id: postId,
             message,
         };
-        return this.api('PUT', `/posts/${postId}`, request);
+        const post = await this.api('PUT', `/posts/${postId}`, request);
+        return this.normalizePlatformPost(post);
     }
     // Add a reaction to a post
     async addReaction(postId, emojiName) {
@@ -110,10 +175,10 @@ export class MattermostClient extends EventEmitter {
     }
     // Download a file attachment
     async downloadFile(fileId) {
-        const url = `${this.config.mattermost.url}/api/v4/files/${fileId}`;
+        const url = `${this.url}/api/v4/files/${fileId}`;
         const response = await fetch(url, {
             headers: {
-                Authorization: `Bearer ${this.config.mattermost.token}`,
+                Authorization: `Bearer ${this.token}`,
             },
         });
         if (!response.ok) {
@@ -124,12 +189,14 @@ export class MattermostClient extends EventEmitter {
     }
     // Get file info (metadata)
     async getFileInfo(fileId) {
-        return this.api('GET', `/files/${fileId}/info`);
+        const file = await this.api('GET', `/files/${fileId}/info`);
+        return this.normalizePlatformFile(file);
     }
     // Get a post by ID (used to verify thread still exists on resume)
     async getPost(postId) {
         try {
-            return await this.api('GET', `/posts/${postId}`);
+            const post = await this.api('GET', `/posts/${postId}`);
+            return this.normalizePlatformPost(post);
         }
         catch {
             return null; // Post doesn't exist or was deleted
@@ -140,7 +207,7 @@ export class MattermostClient extends EventEmitter {
         // Get bot user first
         await this.getBotUser();
         wsLogger.debug(`Bot user ID: ${this.botUserId}`);
-        const wsUrl = this.config.mattermost.url
+        const wsUrl = this.url
             .replace(/^http/, 'ws')
             .concat('/api/v4/websocket');
         return new Promise((resolve, reject) => {
@@ -148,11 +215,13 @@ export class MattermostClient extends EventEmitter {
             this.ws.on('open', () => {
                 wsLogger.debug('WebSocket connected');
                 // Authenticate
-                this.ws.send(JSON.stringify({
-                    seq: 1,
-                    action: 'authentication_challenge',
-                    data: { token: this.config.mattermost.token },
-                }));
+                if (this.ws) {
+                    this.ws.send(JSON.stringify({
+                        seq: 1,
+                        action: 'authentication_challenge',
+                        data: { token: this.token },
+                    }));
+                }
             });
             this.ws.on('message', (data) => {
                 this.lastMessageAt = Date.now(); // Track activity for heartbeat
@@ -200,11 +269,11 @@ export class MattermostClient extends EventEmitter {
                 if (post.user_id === this.botUserId)
                     return;
                 // Only handle messages in our channel
-                if (post.channel_id !== this.config.mattermost.channelId)
+                if (post.channel_id !== this.channelId)
                     return;
-                // Get user info and emit
+                // Get user info and emit (with normalized types)
                 this.getUser(post.user_id).then((user) => {
-                    this.emit('message', post, user);
+                    this.emit('message', this.normalizePlatformPost(post), user);
                 });
             }
             catch (err) {
@@ -222,9 +291,9 @@ export class MattermostClient extends EventEmitter {
                 // Ignore reactions from ourselves
                 if (reaction.user_id === this.botUserId)
                     return;
-                // Get user info and emit
+                // Get user info and emit (with normalized types)
                 this.getUser(reaction.user_id).then((user) => {
-                    this.emit('reaction', reaction, user);
+                    this.emit('reaction', this.normalizePlatformReaction(reaction), user);
                 });
             }
             catch (err) {
@@ -275,29 +344,43 @@ export class MattermostClient extends EventEmitter {
     }
     // Check if user is allowed to use the bot
     isUserAllowed(username) {
-        if (this.config.allowedUsers.length === 0) {
+        if (this.allowedUsers.length === 0) {
             // If no allowlist configured, allow all
             return true;
         }
-        return this.config.allowedUsers.includes(username);
+        return this.allowedUsers.includes(username);
     }
     // Check if message mentions the bot
     isBotMentioned(message) {
-        const botName = escapeRegExp(this.config.mattermost.botName);
+        const botName = escapeRegExp(this.botName);
         // Match @botname at start or with space before
         const mentionPattern = new RegExp(`(^|\\s)@${botName}\\b`, 'i');
         return mentionPattern.test(message);
     }
     // Extract prompt from message (remove bot mention)
     extractPrompt(message) {
-        const botName = escapeRegExp(this.config.mattermost.botName);
+        const botName = escapeRegExp(this.botName);
         return message
             .replace(new RegExp(`(^|\\s)@${botName}\\b`, 'gi'), ' ')
             .trim();
     }
     // Get the bot name
     getBotName() {
-        return this.config.mattermost.botName;
+        return this.botName;
+    }
+    // Get MCP config for permission server
+    getMcpConfig() {
+        return {
+            type: 'mattermost',
+            url: this.url,
+            token: this.token,
+            channelId: this.channelId,
+            allowedUsers: this.allowedUsers,
+        };
+    }
+    // Get platform-specific markdown formatter
+    getFormatter() {
+        return this.formatter;
     }
     // Send typing indicator via WebSocket
     sendTyping(parentId) {
@@ -307,7 +390,7 @@ export class MattermostClient extends EventEmitter {
             action: 'user_typing',
             seq: Date.now(),
             data: {
-                channel_id: this.config.mattermost.channelId,
+                channel_id: this.channelId,
                 parent_id: parentId || '',
             },
         }));

package/dist/platform/mattermost/formatter.d.ts

@@ -0,0 +1,20 @@
+import type { PlatformFormatter } from '../formatter.js';
+/**
+ * Mattermost markdown formatter
+ *
+ * Mattermost uses standard markdown syntax.
+ */
+export declare class MattermostFormatter implements PlatformFormatter {
+    formatBold(text: string): string;
+    formatItalic(text: string): string;
+    formatCode(text: string): string;
+    formatCodeBlock(code: string, language?: string): string;
+    formatUserMention(username: string): string;
+    formatLink(text: string, url: string): string;
+    formatListItem(text: string): string;
+    formatNumberedListItem(number: number, text: string): string;
+    formatBlockquote(text: string): string;
+    formatHorizontalRule(): string;
+    formatHeading(text: string, level: number): string;
+    escapeText(text: string): string;
+}

package/dist/platform/mattermost/formatter.js

@@ -0,0 +1,46 @@
+/**
+ * Mattermost markdown formatter
+ *
+ * Mattermost uses standard markdown syntax.
+ */
+export class MattermostFormatter {
+    formatBold(text) {
+        return `**${text}**`;
+    }
+    formatItalic(text) {
+        return `_${text}_`;
+    }
+    formatCode(text) {
+        return `\`${text}\``;
+    }
+    formatCodeBlock(code, language) {
+        const lang = language || '';
+        return `\`\`\`${lang}\n${code}\n\`\`\``;
+    }
+    formatUserMention(username) {
+        return `@${username}`;
+    }
+    formatLink(text, url) {
+        return `[${text}](${url})`;
+    }
+    formatListItem(text) {
+        return `- ${text}`;
+    }
+    formatNumberedListItem(number, text) {
+        return `${number}. ${text}`;
+    }
+    formatBlockquote(text) {
+        return `> ${text}`;
+    }
+    formatHorizontalRule() {
+        return '---';
+    }
+    formatHeading(text, level) {
+        const hashes = '#'.repeat(Math.min(Math.max(level, 1), 6));
+        return `${hashes} ${text}`;
+    }
+    escapeText(text) {
+        // Escape markdown special characters
+        return text.replace(/([*_`[\]()#+\-.!])/g, '\\$1');
+    }
+}

package/dist/platform/mattermost/permission-api.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Mattermost implementation of Permission API
+ *
+ * Handles permission requests via Mattermost API and WebSocket.
+ */
+import type { PermissionApi, PermissionApiConfig } from '../permission-api.js';
+/**
+ * Create a Mattermost permission API instance
+ */
+export declare function createMattermostPermissionApi(config: PermissionApiConfig): PermissionApi;