claude-threads 0.12.1 → 0.14.0

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;

package/dist/platform/mattermost/permission-api.js

@@ -0,0 +1,139 @@
+/**
+ * Mattermost implementation of Permission API
+ *
+ * Handles permission requests via Mattermost API and WebSocket.
+ */
+import WebSocket from 'ws';
+import { MattermostFormatter } from './formatter.js';
+import { getMe, getUser, createInteractivePost, updatePost, isUserAllowed, } from '../../mattermost/api.js';
+import { mcpLogger } from '../../utils/logger.js';
+/**
+ * Mattermost Permission API implementation
+ */
+class MattermostPermissionApi {
+    apiConfig;
+    config;
+    formatter = new MattermostFormatter();
+    botUserIdCache = null;
+    constructor(config) {
+        this.config = config;
+        this.apiConfig = {
+            url: config.url,
+            token: config.token,
+        };
+    }
+    getFormatter() {
+        return this.formatter;
+    }
+    async getBotUserId() {
+        if (this.botUserIdCache)
+            return this.botUserIdCache;
+        const me = await getMe(this.apiConfig);
+        this.botUserIdCache = me.id;
+        return me.id;
+    }
+    async getUsername(userId) {
+        try {
+            const user = await getUser(this.apiConfig, userId);
+            return user?.username ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    isUserAllowed(username) {
+        return isUserAllowed(username, this.config.allowedUsers);
+    }
+    async createInteractivePost(message, reactions, threadId) {
+        const botUserId = await this.getBotUserId();
+        const post = await createInteractivePost(this.apiConfig, this.config.channelId, message, reactions, threadId, botUserId);
+        return { id: post.id };
+    }
+    async updatePost(postId, message) {
+        await updatePost(this.apiConfig, postId, message);
+    }
+    async waitForReaction(postId, botUserId, timeoutMs) {
+        return new Promise((resolve) => {
+            // Parse WebSocket URL from HTTP URL
+            const wsUrl = this.config.url.replace(/^http/, 'ws') + '/api/v4/websocket';
+            mcpLogger.debug(`Connecting to WebSocket: ${wsUrl}`);
+            const ws = new WebSocket(wsUrl);
+            let resolved = false;
+            const cleanup = () => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.close();
+                }
+            };
+            const timeout = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    cleanup();
+                    resolve(null);
+                }
+            }, timeoutMs);
+            ws.on('open', () => {
+                mcpLogger.debug('WebSocket connected, sending auth...');
+                ws.send(JSON.stringify({
+                    seq: 1,
+                    action: 'authentication_challenge',
+                    data: { token: this.config.token },
+                }));
+            });
+            ws.on('message', async (data) => {
+                if (resolved)
+                    return;
+                try {
+                    const event = JSON.parse(data.toString());
+                    mcpLogger.debug(`WebSocket event: ${event.event}`);
+                    if (event.event === 'reaction_added') {
+                        // Mattermost sends reaction as JSON string
+                        const reaction = typeof event.data.reaction === 'string'
+                            ? JSON.parse(event.data.reaction)
+                            : event.data.reaction;
+                        // Must be on our post
+                        if (reaction.post_id !== postId)
+                            return;
+                        // Must not be the bot's own reaction (adding the options)
+                        if (reaction.user_id === botUserId)
+                            return;
+                        mcpLogger.debug(`Reaction received: ${reaction.emoji_name} from user: ${reaction.user_id}`);
+                        // Got a valid reaction
+                        resolved = true;
+                        clearTimeout(timeout);
+                        cleanup();
+                        resolve({
+                            postId: reaction.post_id,
+                            userId: reaction.user_id,
+                            emojiName: reaction.emoji_name,
+                        });
+                    }
+                }
+                catch (err) {
+                    mcpLogger.debug(`Error parsing WebSocket message: ${err}`);
+                }
+            });
+            ws.on('error', (error) => {
+                mcpLogger.error(`WebSocket error: ${error.message}`);
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    resolve(null);
+                }
+            });
+            ws.on('close', () => {
+                mcpLogger.debug('WebSocket closed');
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    resolve(null);
+                }
+            });
+        });
+    }
+}
+/**
+ * Create a Mattermost permission API instance
+ */
+export function createMattermostPermissionApi(config) {
+    return new MattermostPermissionApi(config);
+}

package/dist/platform/mattermost/types.js

@@ -0,0 +1 @@
+export {};