profclaw 0.0.1-beta.1

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

@@ -0,0 +1,559 @@
+/**
+ * Matrix Provider - Full Implementation
+ *
+ * Matrix Client-Server API v1.x integration using:
+ * - Bearer token authentication (access token)
+ * - Room-based messaging (direct, group, channel)
+ * - Thread support via m.thread relation
+ * - Message send via PUT (idempotent transaction IDs)
+ * - Health via GET /account/whoami
+ * - Room allowlist for security scoping
+ * - E2EE flag (placeholder; actual Olm/Megolm crypto deferred)
+ *
+ * API base: {homeserverUrl}/_matrix/client/v3
+ * Spec: https://spec.matrix.org/v1.9/client-server-api/
+ */
+import { z } from 'zod';
+import { logger } from '../../../utils/logger.js';
+// MATRIX API TYPES
+/** Matrix event types for m.room.message */
+const MatrixMsgType = {
+    TEXT: 'm.text',
+    NOTICE: 'm.notice',
+    EMOTE: 'm.emote',
+    IMAGE: 'm.image',
+    VIDEO: 'm.video',
+    AUDIO: 'm.audio',
+    FILE: 'm.file',
+};
+/** Matrix room join rules */
+const MatrixRoomType = {
+    DIRECT: 'm.direct',
+    GROUP: 'group',
+};
+// CONFIGURATION
+export const MatrixAccountConfigSchema = z.object({
+    id: z.string(),
+    name: z.string().optional(),
+    enabled: z.boolean().default(true),
+    isDefault: z.boolean().optional(),
+    provider: z.literal('matrix'),
+    homeserverUrl: z.string().url().optional(),
+    accessToken: z.string().optional(),
+    userId: z.string().optional(),
+    deviceId: z.string().optional(),
+    enableEncryption: z.boolean().default(false),
+    allowedRoomIds: z.array(z.string()).optional(),
+});
+// METADATA
+const meta = {
+    id: 'matrix',
+    name: 'Matrix',
+    description: 'Matrix protocol rooms with thread and media support',
+    icon: '🔐',
+    docsUrl: 'https://spec.matrix.org/v1.9/client-server-api/',
+    order: 6,
+    color: '#0DBD8B',
+};
+// 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: false,
+    realtime: false, // Polling via /sync or Application Service; no built-in push
+};
+// STATE
+let currentConfig = null;
+/** Monotonic transaction ID counter for idempotent PUT sends */
+let txnCounter = Date.now();
+function nextTxnId() {
+    return `profclaw_${++txnCounter}`;
+}
+// HELPER FUNCTIONS
+function getApiBase(config) {
+    const url = (config ?? currentConfig)?.homeserverUrl ?? '';
+    return `${url.replace(/\/$/, '')}/_matrix/client/v3`;
+}
+function getAuthHeaders(config) {
+    const token = (config ?? currentConfig)?.accessToken;
+    return {
+        'Authorization': token ? `Bearer ${token}` : '',
+        'Content-Type': 'application/json',
+    };
+}
+async function callMatrixApi(endpoint, method = 'GET', body, config) {
+    const base = getApiBase(config);
+    const headers = getAuthHeaders(config);
+    if (!headers['Authorization'] || headers['Authorization'] === 'Bearer ') {
+        return { ok: false, error: 'Access 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 };
+        }
+        const data = await response.json();
+        if (!response.ok) {
+            const errData = data;
+            return {
+                ok: false,
+                status: response.status,
+                error: errData.error || errData.errcode || `HTTP ${response.status}`,
+            };
+        }
+        return { ok: true, data, status: response.status };
+    }
+    catch (error) {
+        logger.error('[Matrix] API call failed:', error instanceof Error ? error : undefined);
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        };
+    }
+}
+/**
+ * Determine chat type from Matrix room membership.
+ * Matrix rooms are always rooms; direct rooms are tagged in account_data.
+ * We use a heuristic: if room_id starts with a known DM prefix it's direct,
+ * otherwise check if userId pattern suggests a DM alias.
+ */
+function getRoomChatType(roomId, isDirect, threadEventId) {
+    if (threadEventId)
+        return 'thread';
+    if (isDirect)
+        return 'direct';
+    // Matrix has no native concept of "channel" vs "group"; we use room id as hint
+    // Rooms with a #alias are treated as channels, others as groups
+    return roomId.startsWith('#') ? 'channel' : 'group';
+}
+/**
+ * Extract the thread root event_id from a Matrix event's m.relates_to,
+ * if rel_type is m.thread.
+ */
+function extractThreadId(content) {
+    const rel = content['m.relates_to'];
+    if (rel?.rel_type === 'm.thread' && rel.event_id) {
+        return rel.event_id;
+    }
+    return undefined;
+}
+/**
+ * Extract the in-reply-to event_id from a Matrix event.
+ */
+function extractReplyToId(content) {
+    const rel = content['m.relates_to'];
+    return rel?.['m.in_reply_to']?.event_id;
+}
+/**
+ * Check whether a room is in the configured allowlist.
+ * If no allowlist is configured, all rooms are allowed.
+ */
+function isRoomAllowed(roomId, config) {
+    const list = config?.allowedRoomIds;
+    if (!list || list.length === 0)
+        return true;
+    return list.includes(roomId);
+}
+/**
+ * Derive a human-readable sender display name from a Matrix user ID.
+ * Format: @localpart:homeserver  →  localpart
+ */
+function displayNameFromUserId(userId) {
+    const match = /^@([^:]+):/.exec(userId);
+    return match ? match[1] : userId;
+}
+// AUTH ADAPTER
+const authAdapter = {
+    getAuthUrl(_state, _scopes) {
+        // Matrix does not use OAuth; authentication is via access tokens
+        // obtained through /login or registration on the homeserver.
+        throw new Error('Matrix does not use OAuth. Obtain an access token via the homeserver ' +
+            '/login endpoint or element.io, and supply it in the configuration.');
+    },
+    async exchangeCode(_code) {
+        throw new Error('Matrix does not use OAuth authorization codes. ' +
+            'Use the Matrix /login endpoint to get an access token.');
+    },
+    verifyWebhook(_signature, _timestamp, _body) {
+        // Matrix Application Services use a hs_token / as_token pair for auth,
+        // not HMAC signatures. Return true as a pass-through; callers should
+        // verify the Authorization header against the configured as_token instead.
+        return true;
+    },
+};
+// OUTBOUND ADAPTER
+const outboundAdapter = {
+    async send(message) {
+        if (!currentConfig?.accessToken) {
+            return { success: false, error: 'Access token not configured' };
+        }
+        if (!message.to) {
+            return { success: false, error: 'Target room ID (to) is required' };
+        }
+        if (!isRoomAllowed(message.to, currentConfig)) {
+            return { success: false, error: `Room ${message.to} is not in the allowlist` };
+        }
+        const content = {
+            msgtype: MatrixMsgType.TEXT,
+            body: message.text ?? '',
+        };
+        // Thread relation
+        if (message.threadId) {
+            content['m.relates_to'] = {
+                rel_type: 'm.thread',
+                event_id: message.threadId,
+                is_falling_back: true,
+                'm.in_reply_to': { event_id: message.replyToId ?? message.threadId },
+            };
+        }
+        else if (message.replyToId) {
+            // Plain reply (not in a thread)
+            content['m.relates_to'] = {
+                'm.in_reply_to': { event_id: message.replyToId },
+            };
+        }
+        const txnId = nextTxnId();
+        const result = await callMatrixApi(`/rooms/${encodeURIComponent(message.to)}/send/m.room.message/${txnId}`, 'PUT', content);
+        if (result.ok && result.data) {
+            return {
+                success: true,
+                messageId: result.data.event_id,
+                threadId: message.threadId,
+            };
+        }
+        return {
+            success: false,
+            error: result.error ?? 'Failed to send message',
+        };
+    },
+    async edit(messageId, channelId, content) {
+        if (!currentConfig?.accessToken) {
+            return { success: false, error: 'Access token not configured' };
+        }
+        if (!isRoomAllowed(channelId, currentConfig)) {
+            return { success: false, error: `Room ${channelId} is not in the allowlist` };
+        }
+        const newText = content.text ?? '';
+        // Matrix edits use m.replace relation
+        const eventContent = {
+            msgtype: MatrixMsgType.TEXT,
+            body: `* ${newText}`,
+            'm.new_content': {
+                msgtype: MatrixMsgType.TEXT,
+                body: newText,
+            },
+            'm.relates_to': {
+                rel_type: 'm.replace',
+                event_id: messageId,
+            },
+        };
+        const txnId = nextTxnId();
+        const result = await callMatrixApi(`/rooms/${encodeURIComponent(channelId)}/send/m.room.message/${txnId}`, 'PUT', eventContent);
+        if (result.ok && result.data) {
+            return {
+                success: true,
+                messageId: result.data.event_id,
+            };
+        }
+        return {
+            success: false,
+            error: result.error ?? 'Failed to edit message',
+        };
+    },
+    async delete(messageId, channelId) {
+        if (!currentConfig?.accessToken) {
+            return { success: false, error: 'Access token not configured' };
+        }
+        if (!isRoomAllowed(channelId, currentConfig)) {
+            return { success: false, error: `Room ${channelId} is not in the allowlist` };
+        }
+        // Matrix redacts (soft-deletes) events via PUT /redact
+        const txnId = nextTxnId();
+        const result = await callMatrixApi(`/rooms/${encodeURIComponent(channelId)}/redact/${encodeURIComponent(messageId)}/${txnId}`, 'PUT', {});
+        return {
+            success: result.ok,
+            error: result.error,
+        };
+    },
+    async react(messageId, channelId, emoji) {
+        if (!currentConfig?.accessToken) {
+            return { success: false };
+        }
+        if (!isRoomAllowed(channelId, currentConfig)) {
+            logger.warn(`[Matrix] react: room ${channelId} not in allowlist`);
+            return { success: false };
+        }
+        // Matrix reactions use m.reaction event type with m.annotation relation
+        const content = {
+            'm.relates_to': {
+                rel_type: 'm.annotation',
+                event_id: messageId,
+                key: emoji,
+            },
+        };
+        const txnId = nextTxnId();
+        const result = await callMatrixApi(`/rooms/${encodeURIComponent(channelId)}/send/m.reaction/${txnId}`, 'PUT', content);
+        return { success: result.ok };
+    },
+    async unreact(messageId, channelId, emoji) {
+        if (!currentConfig?.accessToken) {
+            return { success: false };
+        }
+        if (!isRoomAllowed(channelId, currentConfig)) {
+            logger.warn(`[Matrix] unreact: room ${channelId} not in allowlist`);
+            return { success: false };
+        }
+        // To remove a reaction we must find and redact the m.reaction event.
+        // First, fetch the relations for the target event.
+        const relResult = await callMatrixApi(`/rooms/${encodeURIComponent(channelId)}/relations/${encodeURIComponent(messageId)}/m.annotation/m.reaction`);
+        if (!relResult.ok || !relResult.data) {
+            return { success: false };
+        }
+        const botUserId = currentConfig?.userId;
+        const reactionEvent = relResult.data.chunk.find((e) => e.content['m.relates_to']?.key === emoji &&
+            (!botUserId || e.sender === botUserId));
+        if (!reactionEvent) {
+            // Reaction not found; treat as success (idempotent)
+            return { success: true };
+        }
+        const txnId = nextTxnId();
+        const redactResult = await callMatrixApi(`/rooms/${encodeURIComponent(channelId)}/redact/${encodeURIComponent(reactionEvent.event_id)}/${txnId}`, 'PUT', {});
+        return { success: redactResult.ok };
+    },
+};
+// INBOUND ADAPTER
+const inboundAdapter = {
+    parseMessage(payload) {
+        // Accepts either a raw MatrixEvent or a sync-style wrapper:
+        // { event: MatrixEvent, roomId: string, isDirect?: boolean }
+        let event;
+        let roomId;
+        let isDirect = false;
+        if (payload !== null &&
+            typeof payload === 'object' &&
+            'event' in payload &&
+            'roomId' in payload) {
+            const wrapped = payload;
+            event = wrapped.event;
+            roomId = wrapped.roomId;
+            isDirect = wrapped.isDirect ?? false;
+        }
+        else {
+            event = payload;
+            roomId = event.room_id;
+        }
+        if (!event || event.type !== 'm.room.message')
+            return null;
+        const content = event.content;
+        if (!content.body)
+            return null;
+        // Ignore non-text message types for now (images, files etc. still parsed below)
+        const supportedMsgTypes = [
+            MatrixMsgType.TEXT,
+            MatrixMsgType.NOTICE,
+            MatrixMsgType.EMOTE,
+            MatrixMsgType.IMAGE,
+            MatrixMsgType.VIDEO,
+            MatrixMsgType.AUDIO,
+            MatrixMsgType.FILE,
+        ];
+        if (content.msgtype && !supportedMsgTypes.includes(content.msgtype)) {
+            return null;
+        }
+        if (!isRoomAllowed(roomId, currentConfig)) {
+            logger.debug(`[Matrix] parseMessage: ignoring event from non-allowlisted room ${roomId}`);
+            return null;
+        }
+        const threadId = extractThreadId(content);
+        const replyToId = extractReplyToId(content);
+        const chatType = getRoomChatType(roomId, isDirect, threadId);
+        const attachments = [];
+        if (content.url && content.msgtype) {
+            const typeMap = {
+                [MatrixMsgType.IMAGE]: 'image',
+                [MatrixMsgType.VIDEO]: 'video',
+                [MatrixMsgType.AUDIO]: 'audio',
+                [MatrixMsgType.FILE]: 'file',
+            };
+            const attachType = typeMap[content.msgtype] ?? 'file';
+            attachments.push({
+                type: attachType,
+                url: content.url,
+                name: content.body,
+                mimeType: content.info?.mimetype,
+                size: content.info?.size,
+            });
+        }
+        return {
+            id: event.event_id,
+            provider: 'matrix',
+            accountId: currentConfig?.id ?? 'default',
+            senderId: event.sender,
+            senderName: displayNameFromUserId(event.sender),
+            senderUsername: event.sender,
+            chatType,
+            chatId: roomId,
+            chatName: undefined, // Resolved separately via /rooms/{roomId}/state/m.room.name
+            threadId,
+            replyToId,
+            text: content.body,
+            rawContent: event,
+            timestamp: new Date(event.origin_server_ts),
+            attachments: attachments.length > 0 ? attachments : undefined,
+        };
+    },
+    parseCommand(_payload) {
+        // Matrix does not have native slash commands.
+        // Slash-command-like behavior can be implemented by inspecting message text,
+        // but that is handled at the application layer, not the provider layer.
+        return null;
+    },
+    parseAction(_payload) {
+        // Matrix does not have native interactive components.
+        return null;
+    },
+    buildCommandResponse(response) {
+        // Used when the application layer processes a text-based command.
+        // Return a Matrix event content object ready for PUT /send.
+        return {
+            msgtype: response.responseType === 'ephemeral' ? MatrixMsgType.NOTICE : MatrixMsgType.TEXT,
+            body: response.text ?? '',
+        };
+    },
+    buildActionResponse(response) {
+        return {
+            msgtype: MatrixMsgType.TEXT,
+            body: response.text ?? '',
+        };
+    },
+};
+// STATUS ADAPTER
+const statusAdapter = {
+    isConfigured(config) {
+        return !!(config.homeserverUrl && config.accessToken && config.userId);
+    },
+    async checkHealth(config) {
+        if (!config.homeserverUrl || !config.accessToken) {
+            return { connected: false, error: 'homeserverUrl and accessToken are required' };
+        }
+        const matrixConfig = {
+            id: config.id,
+            name: config.name,
+            enabled: config.enabled ?? true,
+            isDefault: config.isDefault,
+            provider: 'matrix',
+            homeserverUrl: config.homeserverUrl,
+            accessToken: config.accessToken,
+            userId: config.userId,
+            deviceId: config.deviceId,
+            enableEncryption: config.enableEncryption ?? false,
+            allowedRoomIds: config.allowedRoomIds,
+        };
+        const start = Date.now();
+        const result = await callMatrixApi('/account/whoami', 'GET', undefined, matrixConfig);
+        const latencyMs = Date.now() - start;
+        if (result.ok && result.data) {
+            const encryptionNote = config.enableEncryption
+                ? 'E2EE flag set (crypto implementation deferred)'
+                : 'E2EE disabled';
+            return {
+                connected: true,
+                latencyMs,
+                details: {
+                    userId: result.data.user_id,
+                    deviceId: result.data.device_id,
+                    isGuest: result.data.is_guest ?? false,
+                    homeserverUrl: config.homeserverUrl,
+                    encryptionStatus: encryptionNote,
+                    allowedRoomsCount: config.allowedRoomIds?.length ?? 'unrestricted',
+                },
+            };
+        }
+        return {
+            connected: false,
+            latencyMs,
+            error: result.error ?? 'Failed to connect to homeserver',
+        };
+    },
+};
+// EXPORTED HELPERS
+/**
+ * Parse incoming events from a Matrix /sync response.
+ * Yields normalized IncomingMessage objects for all m.room.message events
+ * in joined rooms that pass the allowlist filter.
+ */
+export function parseSyncResponse(syncResponse, directRoomIds = new Set()) {
+    const messages = [];
+    const joinedRooms = syncResponse.rooms?.join ?? {};
+    for (const [roomId, roomData] of Object.entries(joinedRooms)) {
+        const events = roomData.timeline?.events ?? [];
+        const isDirect = directRoomIds.has(roomId);
+        for (const event of events) {
+            if (event.type !== 'm.room.message')
+                continue;
+            const parsed = inboundAdapter.parseMessage({ event, roomId, isDirect });
+            if (parsed) {
+                messages.push(parsed);
+            }
+        }
+    }
+    return messages;
+}
+/**
+ * Fetch joined room info for a specific room.
+ * Returns room name and whether it's a direct message.
+ */
+export async function getRoomInfo(roomId, config) {
+    const result = await callMatrixApi(`/rooms/${encodeURIComponent(roomId)}/state/m.room.name/`, 'GET', undefined, config ?? currentConfig);
+    if (result.ok && result.data) {
+        return {
+            ok: true,
+            data: {
+                room_id: roomId,
+                name: result.data.name,
+                canonical_alias: result.data.canonical_alias,
+                is_direct: result.data.is_direct,
+            },
+        };
+    }
+    return { ok: false, error: result.error };
+}
+// CONFIG MANAGEMENT
+export function setMatrixConfig(config) {
+    currentConfig = config;
+}
+export function clearMatrixConfig() {
+    currentConfig = null;
+}
+// PROVIDER EXPORT
+export const matrixProvider = {
+    meta,
+    capabilities,
+    defaultConfig: {
+        provider: 'matrix',
+        enabled: true,
+        enableEncryption: false,
+    },
+    configSchema: MatrixAccountConfigSchema,
+    auth: authAdapter,
+    outbound: outboundAdapter,
+    inbound: inboundAdapter,
+    status: statusAdapter,
+};
+export { MatrixMsgType, MatrixRoomType };
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,106 @@
+/**
+ * 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 type { ChatProvider, MattermostAccountConfig, IncomingMessage } from '../types.js';
+interface MattermostPost {
+    id: string;
+    create_at: number;
+    update_at: number;
+    delete_at: number;
+    user_id: string;
+    channel_id: string;
+    root_id: string;
+    message: string;
+    type: string;
+    props?: Record<string, unknown>;
+}
+interface MattermostUser {
+    id: string;
+    username: string;
+    first_name?: string;
+    last_name?: string;
+    nickname?: string;
+    email?: string;
+}
+interface MattermostChannel {
+    id: string;
+    type: string;
+    name: string;
+    display_name?: string;
+    team_id?: string;
+}
+/**
+ * Outgoing webhook payload from Mattermost
+ * Sent by Mattermost when a message matches an outgoing webhook trigger.
+ */
+interface MattermostWebhookPayload {
+    token?: string;
+    team_id?: string;
+    team_domain?: string;
+    channel_id?: string;
+    channel_name?: string;
+    user_id?: string;
+    user_name?: string;
+    post_id?: string;
+    text?: string;
+    timestamp?: string;
+    trigger_word?: string;
+    file_ids?: string;
+}
+export declare const MattermostAccountConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    isDefault: z.ZodOptional<z.ZodBoolean>;
+    provider: z.ZodLiteral<"mattermost">;
+    serverUrl: z.ZodOptional<z.ZodString>;
+    botToken: z.ZodOptional<z.ZodString>;
+    webhookUrl: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodString>;
+    allowedChannelIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    provider: "mattermost";
+    enabled: boolean;
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    teamId?: string | undefined;
+    botToken?: string | undefined;
+    webhookUrl?: string | undefined;
+    allowedChannelIds?: string[] | undefined;
+    serverUrl?: string | undefined;
+}, {
+    id: string;
+    provider: "mattermost";
+    name?: string | undefined;
+    isDefault?: boolean | undefined;
+    enabled?: boolean | undefined;
+    teamId?: string | undefined;
+    botToken?: string | undefined;
+    webhookUrl?: string | undefined;
+    allowedChannelIds?: string[] | undefined;
+    serverUrl?: string | undefined;
+}>;
+type MattermostConfig = z.infer<typeof MattermostAccountConfigSchema>;
+/**
+ * Parse an inbound post payload from the Mattermost Events API or WebSocket driver.
+ * Normalizes a full MattermostPost + channel context into an IncomingMessage.
+ */
+export declare function parsePostEvent(post: MattermostPost, channel: MattermostChannel, sender?: MattermostUser): IncomingMessage | null;
+export declare function setMattermostConfig(config: MattermostConfig): void;
+export declare function clearMattermostConfig(): void;
+export declare const mattermostProvider: ChatProvider<MattermostAccountConfig>;
+export type { MattermostConfig, MattermostPost, MattermostWebhookPayload };
+//# sourceMappingURL=index.d.ts.map