@theokit/gateway-mattermost 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,36 @@
1
+ # Changelog
2
+
3
+ ## 2.0.0
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies
8
+ - @theokit/sdk@1.3.0
9
+ - @theokit/gateway@2.0.0
10
+
11
+ ## 1.0.0
12
+
13
+ ### Patch Changes
14
+
15
+ - Updated dependencies
16
+ - @theokit/sdk@1.2.0
17
+ - @theokit/gateway@1.0.0
18
+
19
+ ## [Unreleased]
20
+
21
+ ### Added — `@theokit/gateway-mattermost@0.1.0` (ADRs D397-D404)
22
+
23
+ - Initial release of the Mattermost platform adapter for `@theokit/gateway`.
24
+ - `@mattermost/client@^9.0.0` peer-dep (modern v4 REST + WebSocket gateway).
25
+ - `MattermostAdapter` extending `BasePlatformAdapter`:
26
+ - `connect()` initializes Client4 + WebSocketClient; caches bot userId via `getMe()`.
27
+ - `disconnect()` closes WebSocket; idempotent.
28
+ - `sendMessage()` posts to channel; thread replies set `root_id` from `topicId`.
29
+ - `onInbound()` subscribes to WS `posted` events; single-handler replace semantics (EC-H).
30
+ - Inbound dispatch pipeline (D403, EC-2):
31
+ 1. Drop bot's own posts (loop guard, D275 mirror).
32
+ 2. DMs always dispatch.
33
+ 3. Channels: respond only when mentioned. **Metadata.mentions array checked FIRST** (unambiguous user-id list from API) before falling back to text-regex with **word-boundary** (`\b@${botUsername}\b` — prevents `@theory` matching `@theo`).
34
+ - Channel-type mapping (D402): `D` → `dm`, `G`/`O`/`P` → `group`. Original Mattermost type preserved in `event.mattermost.channelType`.
35
+ - Personal Access Token auth (D401). OAuth deferred to v0.2.
36
+ - File uploads (D404), Slash commands, and ephemeral messages deferred to v0.2 — caller can access `adapter.getClient()` (REST) for escape-hatch use.
package/README.md ADDED
@@ -0,0 +1,88 @@
1
+ # @theokit/gateway-mattermost
2
+
3
+ Mattermost platform adapter for [`@theokit/gateway`](../gateway).
4
+
5
+ Works with self-hosted Mattermost (Docker / Kubernetes / bare metal) and Mattermost Cloud. WebSocket gateway for real-time inbound, REST v4 for outbound.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pnpm add @theokit/sdk @theokit/gateway @theokit/gateway-mattermost
11
+ pnpm add @mattermost/client ws
12
+ ```
13
+
14
+ ## Quick start
15
+
16
+ ```ts
17
+ import { Agent } from "@theokit/sdk";
18
+ import { GatewayRunner } from "@theokit/gateway";
19
+ import { MattermostAdapter } from "@theokit/gateway-mattermost";
20
+
21
+ const adapter = new MattermostAdapter({
22
+ baseUrl: "https://mattermost.acme.com",
23
+ accessToken: process.env.MM_BOT_TOKEN!,
24
+ // Optional: ignore non-DM channels unless explicitly mentioned (default: true).
25
+ // requireMention: true,
26
+ });
27
+
28
+ const runner = new GatewayRunner({
29
+ adapters: [adapter],
30
+ handler: async (event, ctx) => {
31
+ if (event.platform !== "mattermost") return;
32
+ await ctx.reply(`Echo: ${event.text}`);
33
+ },
34
+ });
35
+
36
+ await runner.start();
37
+ ```
38
+
39
+ ## Setup
40
+
41
+ ### Bot account + Personal Access Token
42
+
43
+ 1. Sign in as a Mattermost admin.
44
+ 2. **System Console → Integrations → Bot Accounts** — enable.
45
+ 3. **Account Settings → Account Settings → Display → Show username 'bot' tag** — optional.
46
+ 4. Create a bot account (Integrations → Bot Accounts → Add Bot Account).
47
+ 5. Copy the generated access token (shown once — store securely in `.env`).
48
+ 6. Add the bot to channels where it should listen.
49
+
50
+ ### Required environment
51
+
52
+ ```
53
+ MM_BASE_URL=https://mattermost.acme.com
54
+ MM_BOT_TOKEN=<paste-the-token>
55
+ ```
56
+
57
+ ## Behavior
58
+
59
+ | Mattermost channel type | Adapter `channel.type` | Notes |
60
+ |---|---|---|
61
+ | `D` (Direct Message) | `"dm"` | Always processes inbound. |
62
+ | `G` (Group DM) | `"group"` | Requires `@bot` mention by default. |
63
+ | `O` (Open / Public) | `"group"` | Requires `@bot` mention by default. |
64
+ | `P` (Private) | `"group"` | Requires `@bot` mention by default. |
65
+
66
+ Thread replies (`root_id` set on the Mattermost post) become `channel.type: "thread"` with `topicId` = root post id. Sending with `type: "thread"` + `topicId: <root>` posts as a thread reply.
67
+
68
+ ### Mention guard (EC-2)
69
+
70
+ The default `requireMention: true` is enforced via:
71
+
72
+ 1. **`metadata.mentions` array first** — Mattermost's API returns a list of user-ids mentioned in the post. The adapter checks if the bot's user-id is in this list. No ambiguity.
73
+ 2. **Text regex fallback** — when metadata is absent, the adapter matches `\b@${botUsername}\b` with word boundary. This prevents `@theory_dept` from matching a bot called `theo`.
74
+
75
+ Override with `requireMention: false` to make the bot respond to every message in every channel it's a member of (loud — use cautiously).
76
+
77
+ ## What's NOT supported in v0.1
78
+
79
+ | Feature | Status | Workaround |
80
+ |---|---|---|
81
+ | OAuth auth | Deferred to v0.2 (D401) | Use PAT |
82
+ | File uploads | Deferred to v0.2 (D404) | `adapter.getClient().uploadFile(...)` (escape hatch) |
83
+ | Slash command incoming webhooks | Not supported v0.1 | — |
84
+ | Ephemeral / hidden messages | Not supported v0.1 | — |
85
+
86
+ ## ADRs
87
+
88
+ D397 – D404 in `.claude/knowledge-base/adrs/`.
package/dist/index.cjs ADDED
@@ -0,0 +1,323 @@
1
+ 'use strict';
2
+
3
+ var gateway = require('@theokit/gateway');
4
+
5
+ // src/adapter.ts
6
+
7
+ // src/errors.ts
8
+ var ConfigurationError = class extends Error {
9
+ name = "ConfigurationError";
10
+ code;
11
+ detail;
12
+ constructor(opts) {
13
+ super(opts.message ?? `gateway-mattermost: ${opts.code}`);
14
+ this.code = opts.code;
15
+ this.detail = opts.detail;
16
+ }
17
+ };
18
+ var SDKNotInstalledError = class extends ConfigurationError {
19
+ constructor(pkgName) {
20
+ super({
21
+ code: "sdk_not_installed",
22
+ message: `gateway-mattermost: peer-dep "${pkgName}" not installed. Run: pnpm add ${pkgName}`,
23
+ detail: pkgName
24
+ });
25
+ }
26
+ };
27
+
28
+ // src/client.ts
29
+ async function loadMattermost() {
30
+ try {
31
+ const mod = await import('@mattermost/client');
32
+ return mod;
33
+ } catch {
34
+ throw new SDKNotInstalledError("@mattermost/client");
35
+ }
36
+ }
37
+ async function connectMattermost(opts) {
38
+ const mod = await loadMattermost();
39
+ const client = new mod.Client4();
40
+ client.setUrl(opts.baseUrl);
41
+ client.setToken(opts.accessToken);
42
+ const me = await client.getMe();
43
+ const ws = new mod.WebSocketClient();
44
+ const wsUrl = wsUrlFromBase(opts.baseUrl);
45
+ ws.initialize(wsUrl, opts.accessToken);
46
+ return {
47
+ client,
48
+ ws,
49
+ botUserId: me.id,
50
+ botUsername: me.username,
51
+ channelCache: /* @__PURE__ */ new Map()
52
+ };
53
+ }
54
+ function wsUrlFromBase(baseUrl) {
55
+ const trimmed = baseUrl.replace(/\/$/, "");
56
+ const wsScheme = trimmed.startsWith("https://") ? "wss://" : "ws://";
57
+ const hostPart = trimmed.replace(/^https?:\/\//, "");
58
+ return `${wsScheme}${hostPart}/api/v4/websocket`;
59
+ }
60
+ async function getChannelCached(handle, channelId) {
61
+ const cached = handle.channelCache.get(channelId);
62
+ if (cached !== void 0) return cached;
63
+ try {
64
+ const channel = await handle.client.getChannel(channelId);
65
+ if (handle.channelCache.size >= 200) {
66
+ const firstKey = handle.channelCache.keys().next().value;
67
+ if (firstKey !== void 0) handle.channelCache.delete(firstKey);
68
+ }
69
+ handle.channelCache.set(channelId, channel);
70
+ return channel;
71
+ } catch {
72
+ return void 0;
73
+ }
74
+ }
75
+
76
+ // src/filters.ts
77
+ function shouldRespond(opts) {
78
+ const { post, channelType, botUserId, botUsername, requireMention } = opts;
79
+ if (post.user_id === botUserId) return false;
80
+ if (channelType === "dm") return true;
81
+ if (!requireMention) return true;
82
+ const mentioned = post.metadata?.mentions?.includes(botUserId) ?? false;
83
+ if (mentioned) return true;
84
+ if (botUsername.length > 0 && hasMentionWithBoundary(post.message, botUsername)) {
85
+ return true;
86
+ }
87
+ return false;
88
+ }
89
+ function hasMentionWithBoundary(text, botUsername) {
90
+ const safe = botUsername.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
91
+ const re = new RegExp(`(^|[^\\w])@${safe}(?![\\w.])`, "u");
92
+ return re.test(text);
93
+ }
94
+
95
+ // src/normalize.ts
96
+ function normalizeMattermostType(channel) {
97
+ return channel?.type ?? "O";
98
+ }
99
+ function mapChannelType(rawType, hasRootId) {
100
+ if (hasRootId) return "thread";
101
+ if (rawType === "D") return "dm";
102
+ return "group";
103
+ }
104
+ function postToMessageEvent(post, channel, senderUsername) {
105
+ const rawType = normalizeMattermostType(channel);
106
+ const channelType = mapChannelType(rawType, post.root_id.length > 0);
107
+ return {
108
+ id: post.id,
109
+ platform: "mattermost",
110
+ sender: {
111
+ id: post.user_id,
112
+ ...senderUsername !== void 0 ? { username: senderUsername } : {}
113
+ },
114
+ channel: {
115
+ id: post.channel_id,
116
+ type: channelType,
117
+ ...channelType === "thread" ? { topicId: post.root_id } : {}
118
+ },
119
+ text: post.message,
120
+ receivedAt: post.create_at > 0 ? post.create_at : Date.now(),
121
+ mattermost: {
122
+ postId: post.id,
123
+ channelId: post.channel_id,
124
+ teamId: channel?.team_id ?? "",
125
+ ...post.root_id.length > 0 ? { rootId: post.root_id } : {},
126
+ channelType: rawType,
127
+ raw: post
128
+ }
129
+ };
130
+ }
131
+
132
+ // src/adapter.ts
133
+ var MattermostAdapter = class extends gateway.BasePlatformAdapter {
134
+ platform = "mattermost";
135
+ opts;
136
+ handle;
137
+ inboundHandler;
138
+ wsListener;
139
+ connected = false;
140
+ constructor(opts) {
141
+ super();
142
+ if (opts.baseUrl.length === 0) {
143
+ throw new ConfigurationError({
144
+ code: "base_url_required",
145
+ message: 'gateway-mattermost: opts.baseUrl is empty (e.g. "https://mattermost.acme.com")'
146
+ });
147
+ }
148
+ if (opts.accessToken.length === 0) {
149
+ throw new ConfigurationError({
150
+ code: "access_token_required",
151
+ message: "gateway-mattermost: opts.accessToken is empty (generate one in System Console \u2192 Integrations \u2192 Bot Accounts)"
152
+ });
153
+ }
154
+ this.opts = opts;
155
+ }
156
+ async connect() {
157
+ if (this.connected) return true;
158
+ try {
159
+ this.handle = await connectMattermost({
160
+ baseUrl: this.opts.baseUrl,
161
+ accessToken: this.opts.accessToken
162
+ });
163
+ this.attachWsListener();
164
+ this.connected = true;
165
+ return true;
166
+ } catch (err) {
167
+ const msg = err instanceof Error ? err.message : String(err);
168
+ process.stderr.write(`[gateway-mattermost] connect failed: ${msg}
169
+ `);
170
+ return false;
171
+ }
172
+ }
173
+ async disconnect() {
174
+ if (!this.connected) return;
175
+ if (this.handle !== void 0 && this.wsListener !== void 0) {
176
+ this.handle.ws.removeMessageListener(this.wsListener);
177
+ }
178
+ this.handle?.ws.close();
179
+ this.handle = void 0;
180
+ this.wsListener = void 0;
181
+ this.connected = false;
182
+ this.inboundHandler = void 0;
183
+ }
184
+ async sendMessage(out) {
185
+ if (out.text.length === 0) {
186
+ return { ok: false, error: { code: "empty_text", message: "outbound text is empty" } };
187
+ }
188
+ if (this.handle === void 0) {
189
+ return {
190
+ ok: false,
191
+ error: { code: "not_connected", message: "MattermostAdapter.connect() not called" }
192
+ };
193
+ }
194
+ try {
195
+ const post = await this.handle.client.createPost({
196
+ channel_id: out.channel.id,
197
+ message: out.text,
198
+ ...out.channel.type === "thread" && out.channel.topicId !== void 0 ? { root_id: out.channel.topicId } : {}
199
+ });
200
+ return { ok: true, messageId: post.id };
201
+ } catch (err) {
202
+ return mapMattermostError(err);
203
+ }
204
+ }
205
+ onInbound(handler) {
206
+ this.inboundHandler = handler;
207
+ return () => {
208
+ if (this.inboundHandler === handler) this.inboundHandler = void 0;
209
+ };
210
+ }
211
+ /** Escape hatch: caller can drive REST directly when v0.1 doesn't expose a feature. */
212
+ getClient() {
213
+ return this.handle;
214
+ }
215
+ attachWsListener() {
216
+ if (this.handle === void 0) return;
217
+ const handle = this.handle;
218
+ this.wsListener = (msg) => {
219
+ if (msg.event !== "posted") return;
220
+ void this.processPostedEvent(handle, msg).catch((err) => {
221
+ const m = err instanceof Error ? err.message : String(err);
222
+ process.stderr.write(`[gateway-mattermost] processPostedEvent failed: ${m}
223
+ `);
224
+ });
225
+ };
226
+ handle.ws.addMessageListener(this.wsListener);
227
+ }
228
+ async processPostedEvent(handle, msg) {
229
+ const post = parsePostFromWS(msg);
230
+ if (post === void 0) return;
231
+ const channel = await getChannelCached(handle, post.channel_id);
232
+ const rawType = normalizeMattermostType(channel);
233
+ const channelType = mapChannelType(rawType, post.root_id.length > 0);
234
+ const requireMention = this.opts.requireMention ?? true;
235
+ if (!shouldRespond({
236
+ post,
237
+ channelType,
238
+ botUserId: handle.botUserId,
239
+ botUsername: handle.botUsername,
240
+ requireMention
241
+ })) {
242
+ return;
243
+ }
244
+ const senderUsername = typeof msg.data.sender_name === "string" ? msg.data.sender_name.replace(/^@/, "") : void 0;
245
+ const event = postToMessageEvent(post, channel, senderUsername);
246
+ if (this.inboundHandler === void 0) return;
247
+ try {
248
+ await this.inboundHandler(event);
249
+ } catch (err) {
250
+ const m = err instanceof Error ? err.message : String(err);
251
+ process.stderr.write(`[gateway-mattermost] handler threw: ${m}
252
+ `);
253
+ }
254
+ }
255
+ };
256
+ function parsePostFromWS(msg) {
257
+ const raw = msg.data?.post;
258
+ if (typeof raw !== "string") return void 0;
259
+ try {
260
+ const parsed = JSON.parse(raw);
261
+ if (typeof parsed.id !== "string" || typeof parsed.user_id !== "string" || typeof parsed.channel_id !== "string" || typeof parsed.message !== "string") {
262
+ return void 0;
263
+ }
264
+ return {
265
+ id: parsed.id,
266
+ user_id: parsed.user_id,
267
+ channel_id: parsed.channel_id,
268
+ root_id: typeof parsed.root_id === "string" ? parsed.root_id : "",
269
+ message: parsed.message,
270
+ create_at: typeof parsed.create_at === "number" ? parsed.create_at : 0,
271
+ metadata: parsed.metadata
272
+ };
273
+ } catch {
274
+ return void 0;
275
+ }
276
+ }
277
+ function mapMattermostError(err) {
278
+ const e = err;
279
+ const status = e.status_code ?? 0;
280
+ if (status === 429) {
281
+ return {
282
+ ok: false,
283
+ error: { code: "rate_limit", message: e.message ?? "Mattermost rate limit" }
284
+ };
285
+ }
286
+ if (status === 401 || status === 403) {
287
+ return {
288
+ ok: false,
289
+ error: {
290
+ code: "permission_denied",
291
+ message: e.message ?? "Mattermost auth/permission error"
292
+ }
293
+ };
294
+ }
295
+ if (status === 400) {
296
+ return {
297
+ ok: false,
298
+ error: { code: "invalid_request", message: e.message ?? "Mattermost rejected request" }
299
+ };
300
+ }
301
+ return {
302
+ ok: false,
303
+ error: {
304
+ code: "send_failed",
305
+ message: e.message ?? (err instanceof Error ? err.message : String(err))
306
+ }
307
+ };
308
+ }
309
+
310
+ exports.ConfigurationError = ConfigurationError;
311
+ exports.MattermostAdapter = MattermostAdapter;
312
+ exports.SDKNotInstalledError = SDKNotInstalledError;
313
+ exports.connectMattermost = connectMattermost;
314
+ exports.getChannelCached = getChannelCached;
315
+ exports.hasMentionWithBoundary = hasMentionWithBoundary;
316
+ exports.mapChannelType = mapChannelType;
317
+ exports.normalizeMattermostType = normalizeMattermostType;
318
+ exports.parsePostFromWS = parsePostFromWS;
319
+ exports.postToMessageEvent = postToMessageEvent;
320
+ exports.shouldRespond = shouldRespond;
321
+ exports.wsUrlFromBase = wsUrlFromBase;
322
+ //# sourceMappingURL=index.cjs.map
323
+ //# sourceMappingURL=index.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/errors.ts","../src/client.ts","../src/filters.ts","../src/normalize.ts","../src/adapter.ts"],"names":["BasePlatformAdapter"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Typed errors for `@theokit/gateway-mattermost`.\n */\n\n/** @knipignore — public input shape for `ConfigurationError` constructor (caller-extensible). */\nexport interface ConfigurationErrorOptions {\n readonly code: string;\n readonly message?: string;\n readonly detail?: string;\n}\n\nexport class ConfigurationError extends Error {\n override readonly name = \"ConfigurationError\";\n readonly code: string;\n readonly detail: string | undefined;\n constructor(opts: ConfigurationErrorOptions) {\n super(opts.message ?? `gateway-mattermost: ${opts.code}`);\n this.code = opts.code;\n this.detail = opts.detail;\n }\n}\n\nexport class SDKNotInstalledError extends ConfigurationError {\n constructor(pkgName: string) {\n super({\n code: \"sdk_not_installed\",\n message: `gateway-mattermost: peer-dep \"${pkgName}\" not installed. Run: pnpm add ${pkgName}`,\n detail: pkgName,\n });\n }\n}\n","/**\n * Wrapper over `@mattermost/client` — lazy import + lifecycle.\n *\n * Owns:\n * - Client4 (REST) for outbound posts + channel/user lookup.\n * - WebSocketClient for real-time `posted` events.\n */\n\nimport { SDKNotInstalledError } from \"./errors.js\";\nimport type { MattermostChannel, MattermostPost } from \"./types.js\";\n\ninterface Client4Like {\n setUrl(url: string): void;\n setToken(token: string): void;\n getMe(): Promise<{ id: string; username: string }>;\n getChannel(channelId: string): Promise<MattermostChannel>;\n createPost(post: {\n channel_id: string;\n message: string;\n root_id?: string;\n }): Promise<MattermostPost>;\n}\n\ninterface WebSocketClientLike {\n initialize(url: string, token: string): void;\n addMessageListener(listener: (msg: WSMessage) => void): void;\n removeMessageListener(listener: (msg: WSMessage) => void): void;\n close(): void;\n}\n\nexport interface WSMessage {\n readonly event: string;\n readonly data: Record<string, unknown>;\n readonly broadcast?: { readonly channel_id?: string; readonly team_id?: string };\n}\n\ninterface MattermostModule {\n Client4: new () => Client4Like;\n WebSocketClient: new () => WebSocketClientLike;\n}\n\nasync function loadMattermost(): Promise<MattermostModule> {\n try {\n const mod = await import(\"@mattermost/client\");\n return mod as unknown as MattermostModule;\n } catch {\n throw new SDKNotInstalledError(\"@mattermost/client\");\n }\n}\n\nexport interface MattermostClientHandle {\n readonly client: Client4Like;\n readonly ws: WebSocketClientLike;\n readonly botUserId: string;\n readonly botUsername: string;\n /** Channel-id LRU cache (max 200) to avoid extra getChannel calls. */\n readonly channelCache: Map<string, MattermostChannel>;\n}\n\nexport interface ConnectOptions {\n readonly baseUrl: string;\n readonly accessToken: string;\n}\n\nexport async function connectMattermost(opts: ConnectOptions): Promise<MattermostClientHandle> {\n const mod = await loadMattermost();\n const client = new mod.Client4();\n client.setUrl(opts.baseUrl);\n client.setToken(opts.accessToken);\n const me = await client.getMe();\n const ws = new mod.WebSocketClient();\n const wsUrl = wsUrlFromBase(opts.baseUrl);\n ws.initialize(wsUrl, opts.accessToken);\n return {\n client,\n ws,\n botUserId: me.id,\n botUsername: me.username,\n channelCache: new Map(),\n };\n}\n\n/**\n * Convert REST base URL to WebSocket URL:\n * `https://x.com` → `wss://x.com/api/v4/websocket`\n * `http://localhost:8065` → `ws://localhost:8065/api/v4/websocket`\n *\n * @public — exported for unit tests + consumer-side reuse.\n */\nexport function wsUrlFromBase(baseUrl: string): string {\n const trimmed = baseUrl.replace(/\\/$/, \"\");\n const wsScheme = trimmed.startsWith(\"https://\") ? \"wss://\" : \"ws://\";\n const hostPart = trimmed.replace(/^https?:\\/\\//, \"\");\n return `${wsScheme}${hostPart}/api/v4/websocket`;\n}\n\nexport async function getChannelCached(\n handle: MattermostClientHandle,\n channelId: string,\n): Promise<MattermostChannel | undefined> {\n const cached = handle.channelCache.get(channelId);\n if (cached !== undefined) return cached;\n try {\n const channel = await handle.client.getChannel(channelId);\n // LRU cap: drop oldest when full.\n if (handle.channelCache.size >= 200) {\n const firstKey = handle.channelCache.keys().next().value;\n if (firstKey !== undefined) handle.channelCache.delete(firstKey);\n }\n handle.channelCache.set(channelId, channel);\n return channel;\n } catch {\n return undefined;\n }\n}\n","/**\n * Inbound dispatch pipeline (D403, EC-2).\n *\n * Order matters — these checks compose:\n *\n * 1. Loop guard: drop bot's own posts (D275 mirror).\n * 2. DM channels: always respond.\n * 3. `requireMention === false`: respond.\n * 4. **Metadata.mentions** array contains bot user-id → respond (PRIORITY).\n * 5. **Word-boundary text regex** `\\b@${botUsername}\\b` → respond.\n * 6. Else: ignore.\n *\n * EC-2: substring match (`post.message.includes(\"@theo\")`) catches\n * `@theory_dept` and dispatches false-positive. The fix is two-fold:\n * prefer the unambiguous `metadata.mentions` array (API-provided\n * user-ids), and when text fallback is required, use `\\b` boundaries.\n */\n\nimport type { MattermostPost } from \"./types.js\";\n\n/** @knipignore — input shape for `shouldRespond`; useful for callers wrapping the filter pipeline. */\nexport interface ShouldRespondOptions {\n readonly post: MattermostPost;\n readonly channelType: \"dm\" | \"group\" | \"thread\";\n readonly botUserId: string;\n readonly botUsername: string;\n readonly requireMention: boolean;\n}\n\nexport function shouldRespond(opts: ShouldRespondOptions): boolean {\n const { post, channelType, botUserId, botUsername, requireMention } = opts;\n // 1. Loop guard.\n if (post.user_id === botUserId) return false;\n // 2. DM — always.\n if (channelType === \"dm\") return true;\n // 3. Opt-out of mention enforcement.\n if (!requireMention) return true;\n // 4. metadata.mentions takes priority — never ambiguous.\n const mentioned = post.metadata?.mentions?.includes(botUserId) ?? false;\n if (mentioned) return true;\n // 5. Text fallback with word boundary (EC-2).\n if (botUsername.length > 0 && hasMentionWithBoundary(post.message, botUsername)) {\n return true;\n }\n return false;\n}\n\n/**\n * Word-boundary match for `@${botUsername}`. Word boundaries land at\n * `\\b` (start/end of `\\w` regions), so `@theo` at the head of `@theory`\n * does NOT match because `\\b` is between `o` and `r` only when the\n * NEXT char is a non-word char.\n *\n * @public — exported for unit tests + consumer-side reuse.\n */\nexport function hasMentionWithBoundary(text: string, botUsername: string): boolean {\n // Escape regex metacharacters in username (Mattermost allows `.`, `_`, `-`).\n const safe = botUsername.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n const re = new RegExp(`(^|[^\\\\w])@${safe}(?![\\\\w.])`, \"u\");\n return re.test(text);\n}\n","/**\n * Inbound normalization: Mattermost Post → MattermostMessageEvent.\n *\n * Channel-type mapping (D402):\n * - `D` (Direct) → `\"dm\"`\n * - `G`/`O`/`P` (Group/Open/Private) → `\"group\"`\n * - Posts with `root_id !== \"\"` → `\"thread\"` with `topicId = root_id` (D399).\n */\n\nimport type { MattermostMessageEvent } from \"@theokit/gateway\";\n\nimport type { MattermostChannel, MattermostPost } from \"./types.js\";\n\nexport function normalizeMattermostType(\n channel: MattermostChannel | undefined,\n): \"D\" | \"G\" | \"O\" | \"P\" | (string & {}) {\n return channel?.type ?? \"O\";\n}\n\nexport function mapChannelType(rawType: string, hasRootId: boolean): \"dm\" | \"group\" | \"thread\" {\n if (hasRootId) return \"thread\";\n if (rawType === \"D\") return \"dm\";\n return \"group\";\n}\n\nexport function postToMessageEvent(\n post: MattermostPost,\n channel: MattermostChannel | undefined,\n senderUsername: string | undefined,\n): MattermostMessageEvent {\n const rawType = normalizeMattermostType(channel);\n const channelType = mapChannelType(rawType, post.root_id.length > 0);\n return {\n id: post.id,\n platform: \"mattermost\",\n sender: {\n id: post.user_id,\n ...(senderUsername !== undefined ? { username: senderUsername } : {}),\n },\n channel: {\n id: post.channel_id,\n type: channelType,\n ...(channelType === \"thread\" ? { topicId: post.root_id } : {}),\n },\n text: post.message,\n receivedAt: post.create_at > 0 ? post.create_at : Date.now(),\n mattermost: {\n postId: post.id,\n channelId: post.channel_id,\n teamId: channel?.team_id ?? \"\",\n ...(post.root_id.length > 0 ? { rootId: post.root_id } : {}),\n channelType: rawType,\n raw: post,\n },\n };\n}\n","/**\n * `MattermostAdapter` — implements BasePlatformAdapter over Client4 + WS.\n * ADRs D397-D404.\n *\n * @public\n */\n\nimport {\n BasePlatformAdapter,\n type MessageEvent as GatewayMessageEvent,\n type OutboundMessage,\n type SendResult,\n} from \"@theokit/gateway\";\n\nimport {\n type ConnectOptions,\n connectMattermost,\n getChannelCached,\n type MattermostClientHandle,\n type WSMessage,\n} from \"./client.js\";\nimport { ConfigurationError } from \"./errors.js\";\nimport { shouldRespond } from \"./filters.js\";\nimport { mapChannelType, normalizeMattermostType, postToMessageEvent } from \"./normalize.js\";\nimport type { MattermostAdapterOptions, MattermostPost } from \"./types.js\";\n\nexport class MattermostAdapter extends BasePlatformAdapter {\n readonly platform = \"mattermost\" as const;\n private readonly opts: MattermostAdapterOptions;\n private handle: MattermostClientHandle | undefined;\n private inboundHandler: ((event: GatewayMessageEvent) => Promise<void>) | undefined;\n private wsListener: ((msg: WSMessage) => void) | undefined;\n private connected = false;\n\n constructor(opts: MattermostAdapterOptions) {\n super();\n if (opts.baseUrl.length === 0) {\n throw new ConfigurationError({\n code: \"base_url_required\",\n message: 'gateway-mattermost: opts.baseUrl is empty (e.g. \"https://mattermost.acme.com\")',\n });\n }\n if (opts.accessToken.length === 0) {\n throw new ConfigurationError({\n code: \"access_token_required\",\n message:\n \"gateway-mattermost: opts.accessToken is empty (generate one in System Console → Integrations → Bot Accounts)\",\n });\n }\n this.opts = opts;\n }\n\n async connect(): Promise<boolean> {\n if (this.connected) return true;\n try {\n this.handle = await connectMattermost({\n baseUrl: this.opts.baseUrl,\n accessToken: this.opts.accessToken,\n } satisfies ConnectOptions);\n this.attachWsListener();\n this.connected = true;\n return true;\n } catch (err) {\n const msg = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-mattermost] connect failed: ${msg}\\n`);\n return false;\n }\n }\n\n async disconnect(): Promise<void> {\n if (!this.connected) return;\n if (this.handle !== undefined && this.wsListener !== undefined) {\n this.handle.ws.removeMessageListener(this.wsListener);\n }\n this.handle?.ws.close();\n this.handle = undefined;\n this.wsListener = undefined;\n this.connected = false;\n this.inboundHandler = undefined;\n }\n\n async sendMessage(out: OutboundMessage): Promise<SendResult> {\n if (out.text.length === 0) {\n return { ok: false, error: { code: \"empty_text\", message: \"outbound text is empty\" } };\n }\n if (this.handle === undefined) {\n return {\n ok: false,\n error: { code: \"not_connected\", message: \"MattermostAdapter.connect() not called\" },\n };\n }\n try {\n const post = await this.handle.client.createPost({\n channel_id: out.channel.id,\n message: out.text,\n ...(out.channel.type === \"thread\" && out.channel.topicId !== undefined\n ? { root_id: out.channel.topicId }\n : {}),\n });\n return { ok: true, messageId: post.id };\n } catch (err) {\n return mapMattermostError(err);\n }\n }\n\n onInbound(handler: (event: GatewayMessageEvent) => Promise<void>): () => void {\n // EC-H: replace, not stack.\n this.inboundHandler = handler;\n return () => {\n if (this.inboundHandler === handler) this.inboundHandler = undefined;\n };\n }\n\n /** Escape hatch: caller can drive REST directly when v0.1 doesn't expose a feature. */\n getClient(): MattermostClientHandle | undefined {\n return this.handle;\n }\n\n private attachWsListener(): void {\n if (this.handle === undefined) return;\n const handle = this.handle;\n this.wsListener = (msg: WSMessage) => {\n if (msg.event !== \"posted\") return;\n void this.processPostedEvent(handle, msg).catch((err: unknown) => {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-mattermost] processPostedEvent failed: ${m}\\n`);\n });\n };\n handle.ws.addMessageListener(this.wsListener);\n }\n\n private async processPostedEvent(handle: MattermostClientHandle, msg: WSMessage): Promise<void> {\n const post = parsePostFromWS(msg);\n if (post === undefined) return;\n const channel = await getChannelCached(handle, post.channel_id);\n const rawType = normalizeMattermostType(channel);\n const channelType = mapChannelType(rawType, post.root_id.length > 0);\n const requireMention = this.opts.requireMention ?? true;\n if (\n !shouldRespond({\n post,\n channelType,\n botUserId: handle.botUserId,\n botUsername: handle.botUsername,\n requireMention,\n })\n ) {\n return;\n }\n const senderUsername =\n typeof msg.data.sender_name === \"string\"\n ? (msg.data.sender_name as string).replace(/^@/, \"\")\n : undefined;\n const event = postToMessageEvent(post, channel, senderUsername);\n if (this.inboundHandler === undefined) return;\n try {\n await this.inboundHandler(event);\n } catch (err) {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-mattermost] handler threw: ${m}\\n`);\n }\n }\n}\n\n/**\n * Parse the `data.post` JSON envelope from a Mattermost WS `posted` event.\n *\n * @public — exposed so consumers can drive their own WS listener too.\n */\nexport function parsePostFromWS(msg: WSMessage): MattermostPost | undefined {\n const raw = msg.data?.post;\n if (typeof raw !== \"string\") return undefined;\n try {\n const parsed = JSON.parse(raw) as Partial<MattermostPost>;\n if (\n typeof parsed.id !== \"string\" ||\n typeof parsed.user_id !== \"string\" ||\n typeof parsed.channel_id !== \"string\" ||\n typeof parsed.message !== \"string\"\n ) {\n return undefined;\n }\n return {\n id: parsed.id,\n user_id: parsed.user_id,\n channel_id: parsed.channel_id,\n root_id: typeof parsed.root_id === \"string\" ? parsed.root_id : \"\",\n message: parsed.message,\n create_at: typeof parsed.create_at === \"number\" ? parsed.create_at : 0,\n metadata: parsed.metadata,\n };\n } catch {\n return undefined;\n }\n}\n\ninterface MattermostRestError {\n status_code?: number;\n message?: string;\n}\n\nfunction mapMattermostError(err: unknown): SendResult {\n const e = err as MattermostRestError;\n const status = e.status_code ?? 0;\n if (status === 429) {\n return {\n ok: false,\n error: { code: \"rate_limit\", message: e.message ?? \"Mattermost rate limit\" },\n };\n }\n if (status === 401 || status === 403) {\n return {\n ok: false,\n error: {\n code: \"permission_denied\",\n message: e.message ?? \"Mattermost auth/permission error\",\n },\n };\n }\n if (status === 400) {\n return {\n ok: false,\n error: { code: \"invalid_request\", message: e.message ?? \"Mattermost rejected request\" },\n };\n }\n return {\n ok: false,\n error: {\n code: \"send_failed\",\n message: e.message ?? (err instanceof Error ? err.message : String(err)),\n },\n };\n}\n"]}