@phuetz/code-buddy 1.1.0 → 1.2.0

package/dist/channels/mattermost/index.js

@@ -1,11 +1,37 @@
 /**
  * Mattermost Channel Adapter
  *
- * Connects to Mattermost via WebSocket for real-time messaging.
- * Provides a lightweight in-process adapter for lifecycle and send flows.
+ * Connects to Mattermost via its real-time WebSocket gateway
+ * (`/api/v4/websocket`) for inbound events and the REST API
+ * (`/api/v4/posts`) for outbound messages.
+ *
+ * Transport details:
+ * - Auth: a personal-access / bot token (`config.token`) is sent both as a
+ *   `Bearer` header on REST calls and via the WebSocket
+ *   `authentication_challenge` action after the socket opens.
+ * - Inbound: the WS pushes JSON events; `posted` events carry the new post as
+ *   a nested JSON string which we parse into an `InboundMessage`.
+ * - Outbound: `send()` POSTs `{channel_id, message}` to `/api/v4/posts`.
+ * - Resilience: unintended socket drops are recovered through the shared
+ *   `ReconnectionManager` (exponential backoff + jitter), the same idiom used
+ *   by the discord / slack / imessage adapters. An explicit `disconnect()`
+ *   sets a `closing` flag and cancels any pending reconnect so a deliberate
+ *   close never spins the backoff loop.
  */
+import WebSocket from 'ws';
 import { logger } from '../../utils/logger.js';
-import { BaseChannel } from '../core.js';
+import { BaseChannel, } from '../core.js';
+import { ReconnectionManager } from '../reconnection-manager.js';
+/** Bounded wait for the WS upgrade + auth handshake before failing connect(). */
+const MM_CONNECT_TIMEOUT_MS = 30000;
+/**
+ * Legacy in-process adapter.
+ *
+ * @deprecated The real transport now lives in {@link MattermostChannel}, which
+ * opens a genuine WebSocket and POSTs through the REST API. This class is kept
+ * only for backward-compatible imports (`channels/index.ts` re-export and the
+ * `new-channels.test.ts` lifecycle suite) and performs no network I/O.
+ */
 export class MattermostAdapter {
     config;
     running = false;
@@ -16,14 +42,14 @@ export class MattermostAdapter {
         if (this.running) {
             throw new Error('MattermostAdapter is already running');
         }
-        logger.debug('MattermostAdapter: connecting via WebSocket', { url: this.config.url });
+        logger.debug('MattermostAdapter: starting (in-process compatibility shim)', { url: this.config.url });
         this.running = true;
     }
     async stop() {
         if (!this.running) {
             throw new Error('MattermostAdapter is not running');
         }
-        logger.debug('MattermostAdapter: disconnecting');
+        logger.debug('MattermostAdapter: stopping');
         this.running = false;
     }
     isRunning() {
@@ -53,8 +79,26 @@ export class MattermostAdapter {
         return { ...this.config };
     }
 }
+/**
+ * Convert an `http(s)://host[:port]` base URL into the WebSocket gateway URL.
+ *
+ * The `^http` anchor maps `https → wss` and `http → ws` cleanly without
+ * accidentally rewriting an `http` that appears later in the string.
+ */
+function toWebSocketUrl(baseUrl) {
+    const wsBase = baseUrl.replace(/\/+$/, '').replace(/^http/, 'ws');
+    return `${wsBase}/api/v4/websocket`;
+}
 export class MattermostChannel extends BaseChannel {
-    adapter;
+    mmConfig;
+    ws = null;
+    reconnectionManager;
+    /** Monotonic sequence number for outbound WS actions. */
+    seq = 1;
+    /** True once `disconnect()` is in progress so drops aren't treated as faults. */
+    closing = false;
+    /** Guards against resolving the connect() promise more than once. */
+    connectSettled = false;
     constructor(config) {
         super('mattermost', {
             type: 'mattermost',
@@ -67,36 +111,79 @@ export class MattermostChannel extends BaseChannel {
             rateLimit: config.rateLimit,
             options: config.options,
         });
-        this.adapter = new MattermostAdapter({
+        this.mmConfig = {
             url: config.url,
             token: config.token,
             teamId: config.teamId,
+            maxRetries: config.maxRetries,
+            retryDelay: config.retryDelay,
+        };
+        // Persistent WS connection — drops are recovered with shared exponential
+        // backoff (same idiom as discord / slack / imessage).
+        this.reconnectionManager = new ReconnectionManager('mattermost', {
+            maxRetries: this.mmConfig.maxRetries ?? 10,
+            initialDelayMs: this.mmConfig.retryDelay ?? 1000,
+            maxDelayMs: 60000,
         });
     }
+    // ==========================================================================
+    // Lifecycle
+    // ==========================================================================
     async connect() {
-        await this.adapter.start();
-        this.status.connected = true;
-        this.status.authenticated = true;
-        this.status.lastActivity = new Date();
-        this.emit('connected', this.type);
+        this.closing = false;
+        await this.openSocket();
     }
     async disconnect() {
-        if (!this.status.connected)
+        if (!this.status.connected && !this.ws)
             return;
-        await this.adapter.stop();
+        // Mark intentional so the 'close'/'error' handlers don't schedule a
+        // reconnect, then cancel any reconnect already pending.
+        this.closing = true;
+        this.reconnectionManager.cancel();
+        if (this.ws) {
+            try {
+                this.ws.removeAllListeners();
+                this.ws.close();
+            }
+            catch (error) {
+                logger.debug('MattermostChannel: error closing socket', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            this.ws = null;
+        }
         this.status.connected = false;
+        this.status.authenticated = false;
         this.status.lastActivity = new Date();
         this.emit('disconnected', this.type);
     }
     async send(message) {
         try {
-            const result = message.replyTo
-                ? await this.adapter.sendReply(message.channelId, message.replyTo, message.content)
-                : await this.adapter.sendMessage(message.channelId, message.content);
+            const url = `${this.mmConfig.url.replace(/\/+$/, '')}/api/v4/posts`;
+            const body = {
+                channel_id: message.channelId,
+                message: message.content,
+            };
+            if (message.replyTo) {
+                body.root_id = message.replyTo;
+            }
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.mmConfig.token}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => '');
+                throw new Error(`Mattermost API error: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ''}`);
+            }
+            const post = (await response.json());
             this.status.lastActivity = new Date();
             return {
-                success: result.success,
-                messageId: result.postId,
+                success: true,
+                messageId: post.id,
                 timestamp: new Date(),
             };
         }
@@ -108,6 +195,202 @@ export class MattermostChannel extends BaseChannel {
             };
         }
     }
+    // ==========================================================================
+    // WebSocket transport
+    // ==========================================================================
+    openSocket() {
+        return new Promise((resolve, reject) => {
+            this.connectSettled = false;
+            const wsUrl = toWebSocketUrl(this.mmConfig.url);
+            logger.debug('MattermostChannel: opening WebSocket', { wsUrl });
+            let ws;
+            try {
+                ws = new WebSocket(wsUrl);
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+                return;
+            }
+            this.ws = ws;
+            // The WS upgrade can succeed while the server never sends a frame (bad
+            // token held open, wrong service on the port). Without a timeout the
+            // connect() Promise would never settle. Bound the handshake.
+            const connectTimer = setTimeout(() => {
+                if (this.connectSettled)
+                    return;
+                this.connectSettled = true;
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* ignore */
+                }
+                reject(new Error(`Mattermost WebSocket did not authenticate within ${MM_CONNECT_TIMEOUT_MS}ms`));
+            }, MM_CONNECT_TIMEOUT_MS);
+            if (typeof connectTimer.unref === 'function') {
+                connectTimer.unref();
+            }
+            const onConnected = () => {
+                clearTimeout(connectTimer);
+                resolve();
+            };
+            ws.on('open', () => {
+                // Mattermost expects the auth challenge as the first frame after open.
+                this.sendAction('authentication_challenge', { token: this.mmConfig.token });
+            });
+            ws.on('message', (data) => {
+                try {
+                    const event = JSON.parse(data.toString());
+                    this.handleWsEvent(event, onConnected);
+                }
+                catch (error) {
+                    logger.warn('MattermostChannel: failed to parse WS frame', {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            });
+            ws.on('close', () => {
+                clearTimeout(connectTimer);
+                // A close before the handshake settles must reject connect() (don't hang).
+                if (!this.connectSettled) {
+                    this.connectSettled = true;
+                    reject(new Error('Mattermost WebSocket closed before authentication'));
+                }
+                this.handleDrop();
+            });
+            ws.on('error', (error) => {
+                clearTimeout(connectTimer);
+                const err = error instanceof Error ? error : new Error(String(error));
+                if (this.listenerCount('error') > 0) {
+                    this.emit('error', this.type, err);
+                }
+                if (!this.connectSettled) {
+                    this.connectSettled = true;
+                    reject(err);
+                }
+                this.handleDrop();
+            });
+        });
+    }
+    handleWsEvent(event, resolveConnect) {
+        // The `hello` event (or a successful auth reply) confirms the session.
+        const authedReply = event.seq_reply !== undefined && event.status === 'OK';
+        if (event.event === 'hello' || authedReply) {
+            this.onAuthenticated();
+            if (!this.connectSettled) {
+                this.connectSettled = true;
+                resolveConnect();
+            }
+            return;
+        }
+        if (event.event === 'posted') {
+            this.handlePostedEvent(event);
+            return;
+        }
+        // Respond to a server-side ping with a pong when applicable.
+        if (event.event === 'ping') {
+            this.sendAction('pong', {});
+        }
+    }
+    onAuthenticated() {
+        // Connectivity confirmed — reset the shared backoff state so a future drop
+        // starts from delay 0 rather than inheriting a stale retryCount.
+        this.reconnectionManager.onConnected();
+        this.status.connected = true;
+        this.status.authenticated = true;
+        this.status.lastActivity = new Date();
+        this.emit('connected', this.type);
+        logger.debug('MattermostChannel: authenticated and connected');
+    }
+    handlePostedEvent(event) {
+        const rawPost = event.data?.['post'];
+        if (typeof rawPost !== 'string')
+            return;
+        let post;
+        try {
+            post = JSON.parse(rawPost);
+        }
+        catch (error) {
+            logger.warn('MattermostChannel: failed to parse nested post JSON', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        // System posts (joins, header changes, …) have a non-empty `type` — skip.
+        if (post.type)
+            return;
+        const channelName = typeof event.data?.['channel_name'] === 'string'
+            ? event.data['channel_name']
+            : undefined;
+        const inbound = {
+            id: post.id,
+            channel: {
+                id: post.channel_id,
+                type: 'mattermost',
+                name: channelName,
+            },
+            sender: {
+                id: post.user_id,
+            },
+            content: post.message,
+            contentType: 'text',
+            timestamp: post.create_at ? new Date(post.create_at) : new Date(),
+            threadId: post.root_id || undefined,
+            replyTo: post.root_id || undefined,
+            raw: { event, post },
+        };
+        this.status.lastActivity = new Date();
+        const parsed = this.parseCommand(inbound);
+        this.emit('message', parsed);
+        if (parsed.isCommand) {
+            this.emit('command', parsed);
+        }
+    }
+    /**
+     * Handle a socket drop. If the close was intentional (`disconnect()`), do
+     * nothing. Otherwise schedule a reconnect through the shared manager.
+     */
+    handleDrop() {
+        if (this.closing)
+            return;
+        const wasConnected = this.status.connected;
+        this.status.connected = false;
+        this.status.authenticated = false;
+        // Tear down the dead socket so we don't double-handle further events.
+        if (this.ws) {
+            try {
+                this.ws.removeAllListeners();
+            }
+            catch {
+                /* ignore */
+            }
+            this.ws = null;
+        }
+        if (wasConnected) {
+            this.emit('disconnected', this.type);
+        }
+        logger.debug('MattermostChannel: connection dropped, scheduling reconnect');
+        this.reconnectionManager.scheduleReconnect(async () => {
+            await this.openSocket();
+            // onConnected() is called from onAuthenticated() once `hello` arrives.
+        });
+    }
+    sendAction(action, data) {
+        if (this.ws?.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify({
+            seq: this.seq++,
+            action,
+            data,
+        }));
+    }
+    /** Expose the resolved WS gateway URL (handy for diagnostics / tests). */
+    getWebSocketUrl() {
+        return toWebSocketUrl(this.mmConfig.url);
+    }
+    getConfig() {
+        return { ...this.mmConfig };
+    }
 }
-export default MattermostAdapter;
+export default MattermostChannel;
 //# sourceMappingURL=index.js.map

package/dist/channels/nextcloud-talk/index.d.ts

@@ -1,20 +1,18 @@
 /**
  * Nextcloud Talk Channel Adapter
  *
- * Connects to Nextcloud Talk for messaging and room management.
- * Provides a lightweight in-process adapter for lifecycle and room flows.
+ * Connects to Nextcloud Talk (Spreed) for messaging via the real Spreed chat
+ * REST API using an HTTP long-poll receive loop (`lookIntoFuture=1`), with
+ * auto-reconnect through the shared ReconnectionManager (same idiom as
+ * imessage/irc/discord/slack).
  */
+import { EventEmitter } from 'events';
 import { BaseChannel, ChannelConfig, DeliveryResult, OutboundMessage } from '../core.js';
 export interface NextcloudTalkConfig {
     url: string;
     username: string;
     password: string;
 }
-export interface NextcloudTalkChannelConfig extends ChannelConfig {
-    url: string;
-    username: string;
-    password: string;
-}
 export declare class NextcloudTalkAdapter {
     private config;
     private running;
@@ -40,8 +38,91 @@ export declare class NextcloudTalkAdapter {
     }>;
     getConfig(): NextcloudTalkConfig;
 }
+export interface NextcloudTalkChannelConfig extends ChannelConfig {
+    /** Base Nextcloud URL, e.g. https://cloud.example.com (no trailing slash needed). */
+    url: string;
+    /** Nextcloud user for HTTP Basic auth. */
+    username: string;
+    /** App password / login password for HTTP Basic auth. */
+    password: string;
+    /** Optional explicit app password (preferred over `password` if set). */
+    appPassword?: string;
+    /** Optional bearer token — used instead of Basic auth when provided. */
+    token?: string;
+    bearer?: string;
+    /** Conversation/room token to long-poll for inbound messages. */
+    roomToken?: string;
+    /** Long-poll hold timeout in seconds (server-side). Default 30. */
+    pollTimeoutSecs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+}
+/**
+ * Real Nextcloud Talk (Spreed) client. Holds one outstanding long-poll request
+ * against `chat/<roomToken>?lookIntoFuture=1` at a time; the server returns 200
+ * with new messages or 304 on timeout. Drops are recovered via the shared
+ * ReconnectionManager. This is a genuinely persistent connection model — the
+ * same shape as imessage/irc.
+ */
+export declare class NextcloudTalkClient extends EventEmitter {
+    private readonly baseUrl;
+    private readonly username;
+    private readonly password;
+    private readonly bearer;
+    private readonly roomToken;
+    private readonly pollTimeoutSecs;
+    private running;
+    /** True while an intentional disconnect is in progress — suppresses reconnect. */
+    private closing;
+    private reconnecting;
+    private lastKnownMessageId;
+    /** AbortController for the in-flight long-poll request. */
+    private pollAbort;
+    private readonly reconnectionManager;
+    constructor(config: NextcloudTalkChannelConfig);
+    isRunning(): boolean;
+    getRoomToken(): string;
+    /**
+     * Begin the long-poll receive loop. Returns immediately — `connect()` does
+     * NOT block on the first poll (a long-poll can hold open up to
+     * `pollTimeoutSecs`). The first successful poll (200 or 304) emits
+     * 'connected'.
+     */
+    start(): void;
+    /**
+     * Stop the loop, abort the in-flight request, and cancel any pending
+     * reconnect. Idempotent.
+     */
+    stop(): void;
+    private runPollLoop;
+    /**
+     * Issue one long-poll request. Resolves on 200 (with messages emitted) or 304
+     * (timeout, no messages). Throws on network failure / non-2xx-non-304 status
+     * (a real drop → triggers reconnect).
+     */
+    private pollOnce;
+    private toInbound;
+    /** Emit 'connected' exactly once per session (on first successful poll). */
+    private connectedEmitted;
+    private onConnectedOnce;
+    /**
+     * Recover a dropped connection via the shared ReconnectionManager
+     * (exponential backoff + jitter + exhaustion). `scheduleReconnect` is
+     * single-shot, so a failed attempt re-drives it (deferred past the manager's
+     * internal active-guard) until recovery or exhaustion — same idiom as
+     * irc/imessage.
+     */
+    private scheduleReconnect;
+    sendMessage(roomToken: string, text: string): Promise<{
+        success: boolean;
+        messageId?: string;
+    }>;
+    private buildHeaders;
+    private isAbortError;
+}
 export declare class NextcloudTalkChannel extends BaseChannel {
-    private adapter;
+    private client;
+    private readonly ncConfig;
     constructor(config: NextcloudTalkChannelConfig);
     connect(): Promise<void>;
     disconnect(): Promise<void>;