profclaw 0.0.1-beta.1

package/dist/chat/providers/mattermost/index.js

@@ -0,0 +1,425 @@
+/**
+ * Mattermost Provider - Full Implementation
+ *
+ * Mattermost REST API v4 integration using:
+ * - Bot token authentication (Bearer token)
+ * - Channel-based messaging (direct, group, channel)
+ * - Thread support via root_id on posts
+ * - Outgoing webhook format for inbound events
+ * - Health check via GET /api/v4/users/me
+ * - Channel allowlist for security scoping
+ *
+ * API base: {serverUrl}/api/v4
+ * Docs: https://api.mattermost.com/
+ */
+import { z } from 'zod';
+import { logger } from '../../../utils/logger.js';
+// CONFIGURATION
+export const MattermostAccountConfigSchema = z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    enabled: z.boolean().default(true),
+    isDefault: z.boolean().optional(),
+    provider: z.literal('mattermost'),
+    serverUrl: z.string().url().optional(),
+    botToken: z.string().optional(),
+    webhookUrl: z.string().url().optional(),
+    teamId: z.string().optional(),
+    allowedChannelIds: z.array(z.string()).optional(),
+});
+// METADATA
+const meta = {
+    id: 'mattermost',
+    name: 'Mattermost',
+    description: 'Mattermost channels with thread and file attachment support',
+    icon: 'MM',
+    docsUrl: 'https://api.mattermost.com/',
+    order: 12,
+    color: '#0058CC',
+};
+// CAPABILITIES
+const capabilities = {
+    chatTypes: ['direct', 'group', 'channel', 'thread'],
+    send: true,
+    receive: true,
+    slashCommands: false,
+    interactiveComponents: false,
+    reactions: true,
+    edit: true,
+    delete: true,
+    threads: true,
+    media: true,
+    richBlocks: false,
+    oauth: false,
+    webhooks: true,
+    realtime: false, // Polling or WebSocket via driver; outgoing webhooks for inbound
+};
+// STATE
+let currentConfig = null;
+// HELPER FUNCTIONS
+function getApiBase(config) {
+    const url = (config ?? currentConfig)?.serverUrl ?? '';
+    return `${url.replace(/\/$/, '')}/api/v4`;
+}
+function getAuthHeaders(config) {
+    const token = (config ?? currentConfig)?.botToken;
+    return {
+        'Authorization': token ? `Bearer ${token}` : '',
+        'Content-Type': 'application/json',
+    };
+}
+async function callMattermostApi(endpoint, method = 'GET', body, config) {
+    const base = getApiBase(config);
+    const headers = getAuthHeaders(config);
+    if (!headers['Authorization'] || headers['Authorization'] === 'Bearer ') {
+        return { ok: false, error: 'Bot token not configured' };
+    }
+    const url = `${base}${endpoint}`;
+    try {
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (response.status === 200 && method === 'DELETE') {
+            return { ok: true, status: 200 };
+        }
+        if (response.status === 204) {
+            return { ok: true, status: 204 };
+        }
+        const data = await response.json();
+        if (!response.ok) {
+            const errData = data;
+            return {
+                ok: false,
+                status: response.status,
+                error: errData.message || errData.id || `HTTP ${response.status}`,
+            };
+        }
+        return { ok: true, data, status: response.status };
+    }
+    catch (error) {
+        logger.error('[Mattermost] API call failed:', error instanceof Error ? error : undefined);
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Determine chat type from a Mattermost channel type string.
+ * D = direct message, G = group message, O/P = channel.
+ * If a root_id is present on the post, it is a thread reply.
+ */
+function getChannelChatType(channelType, rootId) {
+    if (rootId)
+        return 'thread';
+    if (channelType === 'D')
+        return 'direct';
+    if (channelType === 'G')
+        return 'group';
+    return 'channel';
+}
+/**
+ * Check whether a channel is in the configured allowlist.
+ * If no allowlist is configured, all channels are allowed.
+ */
+function isChannelAllowed(channelId, config) {
+    const list = config?.allowedChannelIds;
+    if (!list || list.length === 0)
+        return true;
+    return list.includes(channelId);
+}
+/**
+ * Derive a human-readable sender display name from a Mattermost user.
+ * Prefers nickname, then full name, then username.
+ */
+function displayNameFromUser(user) {
+    if (user.nickname)
+        return user.nickname;
+    const fullName = [user.first_name, user.last_name].filter(Boolean).join(' ');
+    if (fullName)
+        return fullName;
+    return user.username;
+}
+// AUTH ADAPTER
+const authAdapter = {
+    getAuthUrl(_state, _scopes) {
+        // Mattermost does not use OAuth at the provider level.
+        // Authentication is via bot token obtained from the Mattermost admin console.
+        throw new Error('Mattermost does not use OAuth. Obtain a bot token from the Mattermost ' +
+            'integrations page and supply it in the configuration.');
+    },
+    async exchangeCode(_code) {
+        throw new Error('Mattermost does not use OAuth authorization codes. ' +
+            'Use a bot token from the Mattermost admin console.');
+    },
+    verifyWebhook(_signature, _timestamp, _body) {
+        // Mattermost outgoing webhooks include a token field in the payload.
+        // Token verification should be done against the configured webhook token
+        // in the outgoing webhook settings. Return true here as a pass-through;
+        // callers should verify the token field in the parsed payload.
+        return true;
+    },
+};
+// OUTBOUND ADAPTER
+const outboundAdapter = {
+    async send(message) {
+        if (!currentConfig?.botToken) {
+            return { success: false, error: 'Bot token not configured' };
+        }
+        if (!message.to) {
+            return { success: false, error: 'Target channel ID (to) is required' };
+        }
+        if (!isChannelAllowed(message.to, currentConfig)) {
+            return { success: false, error: `Channel ${message.to} is not in the allowlist` };
+        }
+        const postBody = {
+            channel_id: message.to,
+            message: message.text ?? '',
+        };
+        // Thread reply - set root_id to reply in a thread
+        if (message.threadId) {
+            postBody['root_id'] = message.threadId;
+        }
+        const result = await callMattermostApi('/posts', 'POST', postBody);
+        if (result.ok && result.data) {
+            return {
+                success: true,
+                messageId: result.data.id,
+                threadId: result.data.root_id || undefined,
+            };
+        }
+        return {
+            success: false,
+            error: result.error ?? 'Failed to send message',
+        };
+    },
+    async edit(messageId, _channelId, content) {
+        if (!currentConfig?.botToken) {
+            return { success: false, error: 'Bot token not configured' };
+        }
+        // Note: Mattermost edit does not need channelId - the post ID is sufficient
+        const result = await callMattermostApi(`/posts/${encodeURIComponent(messageId)}`, 'PUT', { id: messageId, message: content.text ?? '' });
+        if (result.ok && result.data) {
+            return {
+                success: true,
+                messageId: result.data.id,
+            };
+        }
+        return {
+            success: false,
+            error: result.error ?? 'Failed to edit message',
+        };
+    },
+    async delete(messageId, _channelId) {
+        if (!currentConfig?.botToken) {
+            return { success: false, error: 'Bot token not configured' };
+        }
+        // Mattermost DELETE /posts/{post_id} soft-deletes the post
+        const result = await callMattermostApi(`/posts/${encodeURIComponent(messageId)}`, 'DELETE');
+        return {
+            success: result.ok,
+            error: result.error,
+        };
+    },
+    async react(messageId, _channelId, emoji) {
+        if (!currentConfig?.botToken) {
+            return { success: false };
+        }
+        // Fetch current user ID to satisfy the reactions API
+        const meResult = await callMattermostApi('/users/me');
+        if (!meResult.ok || !meResult.data) {
+            logger.warn('[Mattermost] react: failed to fetch bot user ID');
+            return { success: false };
+        }
+        const reactionBody = {
+            user_id: meResult.data.id,
+            post_id: messageId,
+            emoji_name: emoji.replace(/:/g, ''),
+        };
+        const result = await callMattermostApi('/reactions', 'POST', reactionBody);
+        return { success: result.ok };
+    },
+    async unreact(messageId, _channelId, emoji) {
+        if (!currentConfig?.botToken) {
+            return { success: false };
+        }
+        const meResult = await callMattermostApi('/users/me');
+        if (!meResult.ok || !meResult.data) {
+            logger.warn('[Mattermost] unreact: failed to fetch bot user ID');
+            return { success: false };
+        }
+        const userId = meResult.data.id;
+        const emojiName = emoji.replace(/:/g, '');
+        // DELETE /users/{user_id}/posts/{post_id}/reactions/{emoji_name}
+        const result = await callMattermostApi(`/users/${encodeURIComponent(userId)}/posts/${encodeURIComponent(messageId)}/reactions/${encodeURIComponent(emojiName)}`, 'DELETE');
+        return { success: result.ok };
+    },
+};
+// INBOUND ADAPTER
+const inboundAdapter = {
+    parseMessage(payload) {
+        // Accepts Mattermost outgoing webhook format:
+        // { token, team_id, channel_id, channel_name, user_id, user_name, post_id, text, ... }
+        if (payload === null || typeof payload !== 'object')
+            return null;
+        const raw = payload;
+        if (!raw.post_id || !raw.channel_id || !raw.user_id)
+            return null;
+        if (!raw.text)
+            return null;
+        if (!isChannelAllowed(raw.channel_id, currentConfig)) {
+            logger.debug(`[Mattermost] parseMessage: ignoring event from non-allowlisted channel ${raw.channel_id}`);
+            return null;
+        }
+        // Mattermost outgoing webhooks do not carry channel type directly.
+        // Default to channel; direct messages typically do not trigger outgoing webhooks.
+        const chatType = getChannelChatType('O');
+        return {
+            id: raw.post_id,
+            provider: 'mattermost',
+            accountId: currentConfig?.id ?? 'default',
+            senderId: raw.user_id,
+            senderName: raw.user_name ?? raw.user_id,
+            senderUsername: raw.user_name,
+            chatType,
+            chatId: raw.channel_id,
+            chatName: raw.channel_name,
+            threadId: undefined,
+            replyToId: undefined,
+            text: raw.text,
+            rawContent: payload,
+            timestamp: raw.timestamp ? new Date(raw.timestamp) : new Date(),
+            attachments: undefined,
+        };
+    },
+    parseCommand(_payload) {
+        // Mattermost slash commands are not handled at the provider level.
+        // The profClaw server can expose a dedicated slash command endpoint separately.
+        return null;
+    },
+    parseAction(_payload) {
+        // Mattermost does not support interactive components in this provider implementation.
+        return null;
+    },
+    buildCommandResponse(response) {
+        // Return a Mattermost outgoing webhook response body.
+        // The response_type controls visibility: in_channel or ephemeral.
+        return {
+            response_type: response.responseType === 'in_channel' ? 'in_channel' : 'ephemeral',
+            text: response.text ?? '',
+        };
+    },
+    buildActionResponse(response) {
+        return {
+            response_type: 'in_channel',
+            text: response.text ?? '',
+        };
+    },
+};
+// STATUS ADAPTER
+const statusAdapter = {
+    isConfigured(config) {
+        return !!(config.serverUrl && config.botToken && config.teamId);
+    },
+    async checkHealth(config) {
+        if (!config.serverUrl || !config.botToken) {
+            return { connected: false, error: 'serverUrl and botToken are required' };
+        }
+        const mattermostConfig = {
+            id: config.id,
+            name: config.name,
+            enabled: config.enabled ?? true,
+            isDefault: config.isDefault,
+            provider: 'mattermost',
+            serverUrl: config.serverUrl,
+            botToken: config.botToken,
+            webhookUrl: config.webhookUrl,
+            teamId: config.teamId,
+            allowedChannelIds: config.allowedChannelIds,
+        };
+        const start = Date.now();
+        const result = await callMattermostApi('/users/me', 'GET', undefined, mattermostConfig);
+        const latencyMs = Date.now() - start;
+        if (result.ok && result.data) {
+            const user = result.data;
+            const displayName = displayNameFromUser(user);
+            return {
+                connected: true,
+                latencyMs,
+                details: {
+                    userId: user.id,
+                    username: user.username,
+                    displayName,
+                    serverUrl: config.serverUrl,
+                    teamId: config.teamId ?? 'not configured',
+                    allowedChannelsCount: config.allowedChannelIds?.length ?? 'unrestricted',
+                    webhookConfigured: !!config.webhookUrl,
+                },
+            };
+        }
+        return {
+            connected: false,
+            latencyMs,
+            error: result.error ?? 'Failed to connect to Mattermost server',
+        };
+    },
+};
+// EXPORTED HELPERS
+/**
+ * Parse an inbound post payload from the Mattermost Events API or WebSocket driver.
+ * Normalizes a full MattermostPost + channel context into an IncomingMessage.
+ */
+export function parsePostEvent(post, channel, sender) {
+    if (!post.id || !post.channel_id || !post.user_id)
+        return null;
+    if (!post.message)
+        return null;
+    if (!isChannelAllowed(post.channel_id, currentConfig)) {
+        logger.debug(`[Mattermost] parsePostEvent: ignoring post from non-allowlisted channel ${post.channel_id}`);
+        return null;
+    }
+    const rootId = post.root_id || undefined;
+    const chatType = getChannelChatType(channel.type, rootId);
+    const senderName = sender ? displayNameFromUser(sender) : post.user_id;
+    return {
+        id: post.id,
+        provider: 'mattermost',
+        accountId: currentConfig?.id ?? 'default',
+        senderId: post.user_id,
+        senderName,
+        senderUsername: sender?.username,
+        chatType,
+        chatId: post.channel_id,
+        chatName: channel.display_name ?? channel.name,
+        threadId: rootId,
+        replyToId: undefined,
+        text: post.message,
+        rawContent: post,
+        timestamp: new Date(post.create_at),
+        attachments: undefined,
+    };
+}
+// CONFIG MANAGEMENT
+export function setMattermostConfig(config) {
+    currentConfig = config;
+}
+export function clearMattermostConfig() {
+    currentConfig = null;
+}
+// PROVIDER EXPORT
+export const mattermostProvider = {
+    meta,
+    capabilities,
+    defaultConfig: {
+        provider: 'mattermost',
+        enabled: true,
+    },
+    configSchema: MattermostAccountConfigSchema,
+    auth: authAdapter,
+    outbound: outboundAdapter,
+    inbound: inboundAdapter,
+    status: statusAdapter,
+};
+//# sourceMappingURL=index.js.map

package/dist/chat/providers/msteams/index.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Microsoft Teams Provider - Full Implementation
+ *
+ * Secure Microsoft Teams integration using the Bot Framework REST API with:
+ * - HMAC-SHA256 signature verification for incoming activities
+ * - OAuth2 client credentials flow (appId + appPassword) for outbound
+ * - Adaptive Cards for rich interactive content
+ * - Team/channel allowlist support
+ * - Message, reaction, and invoke (command) activity parsing
+ *
+ * Uses Bot Framework Connector REST API v3:
+ * https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference
+ */
+import { z } from 'zod';
+import type { ChatProvider, MSTeamsAccountConfig } from '../types.js';
+/** Bot Framework Activity Types */
+declare const ActivityType: {
+    readonly MESSAGE: "message";
+    readonly MESSAGE_REACTION: "messageReaction";
+    readonly INVOKE: "invoke";
+    readonly CONVERSATION_UPDATE: "conversationUpdate";
+    readonly TYPING: "typing";
+    readonly END_OF_CONVERSATION: "endOfConversation";
+    readonly EVENT: "event";
+    readonly INSTALL_UPDATE: "installationUpdate";
+};
+/** Bot Framework Channel IDs */
+declare const ChannelId: {
+    readonly MSTEAMS: "msteams";
+    readonly DIRECTLINE: "directline";
+    readonly EMULATOR: "emulator";
+};
+interface BotFrameworkAccount {
+    id: string;
+    name?: string;
+    aadObjectId?: string;
+    role?: 'user' | 'bot' | 'skill';
+}
+interface BotFrameworkConversation {
+    id: string;
+    name?: string;
+    isGroup?: boolean;
+    conversationType?: 'personal' | 'channel' | 'groupChat';
+    tenantId?: string;
+}
+interface BotFrameworkAttachment {
+    contentType: string;
+    content?: unknown;
+    contentUrl?: string;
+    name?: string;
+    thumbnailUrl?: string;
+}
+interface BotFrameworkReaction {
+    type: string;
+}
+interface TeamsChannelData {
+    team?: {
+        id: string;
+        name?: string;
+        aadGroupId?: string;
+    };
+    channel?: {
+        id: string;
+        name?: string;
+    };
+    tenant?: {
+        id: string;
+    };
+    notification?: {
+        alert: boolean;
+    };
+}
+/** Bot Framework Activity (inbound) */
+interface BotFrameworkActivity {
+    type: string;
+    id?: string;
+    timestamp?: string;
+    localTimestamp?: string;
+    serviceUrl: string;
+    channelId: string;
+    from: BotFrameworkAccount;
+    conversation: BotFrameworkConversation;
+    recipient: BotFrameworkAccount;
+    replyToId?: string;
+    text?: string;
+    textFormat?: 'markdown' | 'plain' | 'xml';
+    attachments?: BotFrameworkAttachment[];
+    channelData?: TeamsChannelData;
+    reactionsAdded?: BotFrameworkReaction[];
+    reactionsRemoved?: BotFrameworkReaction[];
+    /** Invoke activity name (e.g. 'composeExtension/query') */
+    name?: string;
+    /** Invoke activity value */
+    value?: unknown;
+    locale?: string;
+    entities?: Array<{
+        type: string;
+        text?: string;
+        mentioned?: BotFrameworkAccount;
+    }>;
+}
+/** Adaptive Card body */
+interface AdaptiveCard {
+    type: 'AdaptiveCard';
+    version: string;
+    body?: unknown[];
+    actions?: unknown[];
+    msteams?: {
+        width?: 'Full';
+    };
+}
+export declare const MSTeamsAccountConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"msteams">;
+    appId: z.ZodOptional<z.ZodString>;
+    appPassword: z.ZodOptional<z.ZodString>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    allowedTeamIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowedChannelIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    provider: "msteams";
+    enabled: boolean;
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    allowedChannelIds?: string[] | undefined;
+    appId?: string | undefined;
+    appPassword?: string | undefined;
+    tenantId?: string | undefined;
+    allowedTeamIds?: string[] | undefined;
+}, {
+    id: string;
+    provider: "msteams";
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    enabled?: boolean | undefined;
+    allowedChannelIds?: string[] | undefined;
+    appId?: string | undefined;
+    appPassword?: string | undefined;
+    tenantId?: string | undefined;
+    allowedTeamIds?: string[] | undefined;
+}>;
+type MSTeamsConfig = z.infer<typeof MSTeamsAccountConfigSchema>;
+declare function setTeamsConfig(config: MSTeamsConfig): void;
+declare function clearTeamsConfig(): void;
+/**
+ * Check team/channel allowlists. Returns true if the activity should be processed.
+ */
+export declare function isTeamsSenderAllowed(config: MSTeamsConfig, teamId?: string, channelId?: string): {
+    allowed: boolean;
+    reason?: string;
+};
+/**
+ * Verify Bot Framework incoming request using HMAC-SHA256.
+ *
+ * The Bot Framework sends an Authorization header with a JWT signed by
+ * Microsoft's identity platform. For a lightweight HMAC approach (used with
+ * shared secrets / app password), we verify the HMAC-SHA256 of the body.
+ *
+ * Full JWT verification uses the Bot Framework OpenID metadata endpoint.
+ * This implementation provides HMAC-SHA256 verification for environments
+ * that configure a shared secret webhook.
+ */
+export declare function verifyTeamsSignature(appPassword: string | undefined, signature: string | undefined, body: string): Promise<boolean>;
+/**
+ * Build a proactive message target string from a saved activity.
+ * Use this to send messages outside of the request/response cycle.
+ */
+export declare function buildProactiveTarget(serviceUrl: string, conversationId: string): string;
+/**
+ * Parse channel data from a raw activity payload.
+ */
+export declare function extractTeamsChannelData(activity: unknown): TeamsChannelData | undefined;
+/**
+ * Check if an activity is from the MS Teams channel.
+ */
+export declare function isTeamsActivity(payload: unknown): boolean;
+/**
+ * Check if an activity is a message reaction (user reacted to a bot message).
+ */
+export declare function isMessageReactionActivity(payload: unknown): boolean;
+/**
+ * Parse reaction events (reactionsAdded / reactionsRemoved).
+ */
+export declare function parseReactionActivity(payload: unknown): {
+    added: string[];
+    removed: string[];
+    messageId?: string;
+    userId: string;
+} | null;
+export declare const msteamsProvider: ChatProvider<MSTeamsAccountConfig>;
+export { setTeamsConfig, clearTeamsConfig };
+export type { MSTeamsConfig, BotFrameworkActivity, TeamsChannelData, AdaptiveCard };
+export { ActivityType, ChannelId };
+//# sourceMappingURL=index.d.ts.map