@theokit/gateway-matrix 0.1.5 → 0.2.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 +40 -0
- package/README.md +5 -0
- package/dist/index.cjs +78 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +20 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +78 -1
- package/dist/index.js.map +1 -1
- package/package.json +9 -6
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,45 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- b38172b: **The peer floor on `@theokit/gateway` rises with this release.** Every adapter now implements
|
|
8
|
+
`deliver` over `runHandler`, and neither exists in an older core — an adapter installed against one
|
|
9
|
+
does not build. `dep-check` caught that by building the whole workspace against the floor each
|
|
10
|
+
package claimed, which is the one thing a version range cannot tell you by reading it.
|
|
11
|
+
|
|
12
|
+
The floor is set in the version commit rather than here, because a range cannot name a version that
|
|
13
|
+
does not exist yet: raised in the workspace, the same gate then fails the other way round — every
|
|
14
|
+
adapter declaring a floor above the core installed beside it. That is the shape `fa70153` used when
|
|
15
|
+
these ranges were first written.
|
|
16
|
+
|
|
17
|
+
`deliver(event)` — every adapter can now be handed an event that arrived out of band (#83).
|
|
18
|
+
|
|
19
|
+
`onInbound` was the seam every adapter implemented and it had no public counterpart. Six platforms
|
|
20
|
+
self-deliver once connected — long polling, a gateway socket, Socket Mode, a sync loop, IMAP — so
|
|
21
|
+
the asymmetry stayed invisible: `GatewayRunner` worked for eight platforms and silently did nothing
|
|
22
|
+
for LINE and WhatsApp Cloud, whose payloads arrive on an HTTP route the application owns. Every app
|
|
23
|
+
wired those two by hand, beside the runner rather than through it.
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
const outcome = await adapter.deliver(event); // "ok" | "no_handler" | "handler_threw"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The three outcomes are distinguished because a caller acts on them differently: answering a webhook
|
|
30
|
+
200 when nobody was subscribed tells the provider to stop retrying a message nothing received.
|
|
31
|
+
|
|
32
|
+
`BasePlatformAdapter.runHandler` holds the containment once, where ten copies of it used to live —
|
|
33
|
+
a handler is user code, its throw is named as the handler's failure rather than the platform's, and
|
|
34
|
+
delivery continues. Each adapter's `deliver` is one line over it.
|
|
35
|
+
|
|
36
|
+
Also: `gateway-sms`'s `createWebhookServer` now signs against the configured `publicUrl` (#90).
|
|
37
|
+
Twilio verifies against the URL it POSTed to, and behind a proxy that rewrites `host` — a tunnel, an
|
|
38
|
+
ingress, a load balancer terminating TLS — the reconstruction from headers yields the internal
|
|
39
|
+
address, so a correct signature fails on every delivery. `publicUrl` is required by all three
|
|
40
|
+
backend option shapes and documented as "used by signature verifier"; until now no source file read
|
|
41
|
+
it. The header reconstruction stays as the fallback for an app served directly.
|
|
42
|
+
|
|
3
43
|
## 0.1.5
|
|
4
44
|
|
|
5
45
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -4,6 +4,11 @@ Matrix protocol platform adapter for [`@theokit/gateway`](../gateway).
|
|
|
4
4
|
|
|
5
5
|
Decentralized federation. Works with matrix.org, element.io, self-hosted Synapse/Dendrite, etc. Bot in `@bot:matrix.org` can receive from `@alice:element.io` via federation built-in.
|
|
6
6
|
|
|
7
|
+
|
|
8
|
+
## How inbound arrives
|
|
9
|
+
|
|
10
|
+
**Sync loop.** `startClient()` long-polls the homeserver and timeline events reach `onInbound`.
|
|
11
|
+
There is no webhook to host and nothing for an application to authenticate.
|
|
7
12
|
## Install
|
|
8
13
|
|
|
9
14
|
```bash
|
package/dist/index.cjs
CHANGED
|
@@ -234,12 +234,75 @@ var MatrixAdapter = class extends gateway.BasePlatformAdapter {
|
|
|
234
234
|
}
|
|
235
235
|
};
|
|
236
236
|
}
|
|
237
|
-
const res = await this.
|
|
237
|
+
const res = await this.sendHonouringFormat(roomId, out);
|
|
238
238
|
return { ok: true, messageId: res.event_id };
|
|
239
239
|
} catch (err) {
|
|
240
240
|
return mapMatrixError(err);
|
|
241
241
|
}
|
|
242
242
|
}
|
|
243
|
+
/**
|
|
244
|
+
* Send `out`, letting the caller's declared `format` decide the shape.
|
|
245
|
+
*
|
|
246
|
+
* Matrix carries markup in `formatted_body` and declares its type in `format`, whose only
|
|
247
|
+
* value is `org.matrix.custom.html`. That declaration is a promise to every client that the
|
|
248
|
+
* field IS HTML — so only `format: "html"` may use it.
|
|
249
|
+
*
|
|
250
|
+
* **`markdown` deliberately does not.** The first version of this method put the caller's
|
|
251
|
+
* markdown into `formatted_body` and declared it HTML, which was worse than the bug it meant
|
|
252
|
+
* to fix: `**bold**` still rendered as literal asterisks because markdown is not HTML, AND a
|
|
253
|
+
* `<div>` anywhere in the text was parsed as a tag and dropped, so the reader received words
|
|
254
|
+
* the sender never wrote and lost the ones they did. Caught in review; the test that
|
|
255
|
+
* "proved" it was asserting the defect.
|
|
256
|
+
*
|
|
257
|
+
* So Matrix joins LINE, SMS and WhatsApp: it has no markdown mode, and the honest handling is
|
|
258
|
+
* to say once that the declaration is being dropped rather than to fake it.
|
|
259
|
+
*
|
|
260
|
+
* Falls back to `sendTextMessage` when the client does not expose `sendMessage`: it is
|
|
261
|
+
* optional on {@link MatrixSdkClient} because a consumer may inject a narrower double, and
|
|
262
|
+
* losing the formatting is better than losing the message.
|
|
263
|
+
*
|
|
264
|
+
* @internal
|
|
265
|
+
*/
|
|
266
|
+
async sendHonouringFormat(roomId, out) {
|
|
267
|
+
const client = this.client;
|
|
268
|
+
if (out.format !== "html" || client.sendMessage === void 0) {
|
|
269
|
+
this.warnFormatUnsupported(out.format);
|
|
270
|
+
return await client.sendTextMessage(roomId, out.text);
|
|
271
|
+
}
|
|
272
|
+
try {
|
|
273
|
+
return await client.sendMessage(roomId, {
|
|
274
|
+
msgtype: "m.text",
|
|
275
|
+
body: out.text,
|
|
276
|
+
format: "org.matrix.custom.html",
|
|
277
|
+
formatted_body: out.text
|
|
278
|
+
});
|
|
279
|
+
} catch (err) {
|
|
280
|
+
if (!isMalformedRequest(err)) throw err;
|
|
281
|
+
process.stderr.write(
|
|
282
|
+
"[gateway-matrix] homeserver rejected the formatted body; retrying as plain text\n"
|
|
283
|
+
);
|
|
284
|
+
return await client.sendTextMessage(roomId, out.text);
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
/** Whether the "no markdown mode here" warning has already been emitted. */
|
|
288
|
+
warnedAboutFormat = false;
|
|
289
|
+
/**
|
|
290
|
+
* Say, once, that a declared `markdown` has nowhere to go on this platform.
|
|
291
|
+
*
|
|
292
|
+
* Matrix's only markup type is HTML. A caller declaring `markdown` is asking for something
|
|
293
|
+
* the protocol does not have, and putting the markdown in the HTML field would corrupt it.
|
|
294
|
+
*
|
|
295
|
+
* @internal
|
|
296
|
+
*/
|
|
297
|
+
warnFormatUnsupported(format) {
|
|
298
|
+
if (format === void 0 || format === "plain" || format === "html") return;
|
|
299
|
+
if (this.warnedAboutFormat) return;
|
|
300
|
+
this.warnedAboutFormat = true;
|
|
301
|
+
process.stderr.write(
|
|
302
|
+
`[gateway-matrix] format="${format}" was declared, and Matrix has no markdown mode \u2014 its only markup type is HTML. Sending as plain text; this is logged once.
|
|
303
|
+
`
|
|
304
|
+
);
|
|
305
|
+
}
|
|
243
306
|
onInbound(handler) {
|
|
244
307
|
this.inboundHandler = handler;
|
|
245
308
|
return () => {
|
|
@@ -308,6 +371,15 @@ var MatrixAdapter = class extends gateway.BasePlatformAdapter {
|
|
|
308
371
|
`
|
|
309
372
|
);
|
|
310
373
|
}
|
|
374
|
+
/**
|
|
375
|
+
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
376
|
+
*
|
|
377
|
+
* One line over `runHandler`, which owns the containment: a handler is user code, its throw is
|
|
378
|
+
* named as the handler's failure rather than the platform's, and delivery continues.
|
|
379
|
+
*/
|
|
380
|
+
async deliver(event) {
|
|
381
|
+
return this.runHandler(this.inboundHandler, event);
|
|
382
|
+
}
|
|
311
383
|
};
|
|
312
384
|
function isAbortError(err) {
|
|
313
385
|
if (typeof err !== "object" || err === null) return false;
|
|
@@ -316,6 +388,11 @@ function isAbortError(err) {
|
|
|
316
388
|
if (e.code === 20) return true;
|
|
317
389
|
return typeof e.message === "string" && /aborted/i.test(e.message);
|
|
318
390
|
}
|
|
391
|
+
function isMalformedRequest(err) {
|
|
392
|
+
const e = err;
|
|
393
|
+
if (e.httpStatus !== 400) return false;
|
|
394
|
+
return e.errcode === "M_BAD_JSON" || e.errcode === "M_INVALID_PARAM";
|
|
395
|
+
}
|
|
319
396
|
function mapMatrixError(err) {
|
|
320
397
|
const e = err;
|
|
321
398
|
const status = e.httpStatus ?? 0;
|
package/dist/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/errors.ts","../src/alias.ts","../src/client.ts","../src/room-state.ts","../src/normalize.ts","../src/sync.ts","../src/adapter.ts"],"names":["GatewayConfigurationError","BasePlatformAdapter"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Typed errors for `@theokit/gateway-matrix`.\n *\n * `ConfigurationError` extends the shared core `GatewayConfigurationError`\n * base (roadmap M2). Behavior byte-identical (pinned by `tests/errors.test.ts`).\n */\n\nimport { GatewayConfigurationError, type GatewayConfigurationErrorOptions } from \"@theokit/gateway\";\n\n/** @knipignore — public input shape for `ConfigurationError` constructor (caller-extensible). */\nexport type ConfigurationErrorOptions = GatewayConfigurationErrorOptions;\n\n/**\n * Misconfiguration of this adapter, raised before any network call.\n *\n * Extends the shared core base so every gateway package reports configuration faults in one shape:\n * a structured `code` the caller can branch on, tagged with `\"gateway-matrix\"` as the origin. A\n * missing credential or an unsupported option is a programmer error, not a transient failure —\n * these are never retried.\n */\nexport class ConfigurationError extends GatewayConfigurationError {\n override readonly name = \"ConfigurationError\";\n constructor(opts: ConfigurationErrorOptions) {\n super(\"gateway-matrix\", opts);\n }\n}\n\n/**\n * The platform SDK this adapter needs is declared as a peer dependency and is not installed.\n *\n * Raised at connect time rather than at import, so a project that installs several gateway packages\n * only pays for the SDKs of the ones it actually starts. The message names the exact package and\n * the command that installs it.\n */\nexport class SDKNotInstalledError extends ConfigurationError {\n constructor() {\n super({\n code: \"sdk_not_installed\",\n message:\n 'gateway-matrix: peer-dep \"matrix-js-sdk\" not installed. Run: pnpm add matrix-js-sdk',\n detail: \"matrix-js-sdk\",\n });\n }\n}\n\n/**\n * The room is end-to-end encrypted, which this adapter cannot read.\n *\n * E2EE is deferred to v0.2. Raised rather than silently ignoring the room, because a bot that\n * appears connected and never sees a message is far harder to diagnose than one that says why.\n */\nexport class EncryptedRoomError extends ConfigurationError {\n constructor(roomId: string) {\n super({\n code: \"encrypted_room_unsupported\",\n message: `gateway-matrix: room ${roomId} is end-to-end encrypted (E2EE deferred to v0.2)`,\n detail: roomId,\n });\n }\n}\n","/**\n * Matrix alias resolution + caching (D419).\n *\n * Accepts:\n * - Room id (`!abc123:server`) — pass-through.\n * - Alias (`#general:server`) — resolved via `client.getRoomIdForAlias`.\n *\n * Other shapes throw `ConfigurationError({ code: \"invalid_room_ref\" })`.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\n\n/** @knipignore — minimal Client interface `AliasCache.resolve` accepts; useful for callers building their own resolver. */\nexport interface AliasResolverClient {\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n}\n\n/**\n * Resolves a Matrix room alias (`#room:server`) to its room id, remembering the answer.\n *\n * An alias resolves through a server round-trip, and the mapping effectively never changes, so\n * repeating it once per outbound message is pure latency. A value that is already a room id is\n * returned untouched, which lets callers pass either form.\n */\nexport class AliasCache {\n private readonly cache = new Map<string, string>();\n\n /** Returns the room id; resolves aliases via the client + caches. */\n async resolve(client: AliasResolverClient, refOrId: string): Promise<string> {\n if (refOrId.startsWith(\"!\")) return refOrId;\n if (!refOrId.startsWith(\"#\")) {\n throw new ConfigurationError({\n code: \"invalid_room_ref\",\n message: `gateway-matrix: invalid room reference ${JSON.stringify(refOrId)} — expected '!' (room id) or '#' (alias)`,\n });\n }\n const cached = this.cache.get(refOrId);\n if (cached !== undefined) return cached;\n const { room_id } = await client.getRoomIdForAlias(refOrId);\n this.cache.set(refOrId, room_id);\n return room_id;\n }\n\n /** Drop all cached resolutions. Useful for tests + admin-rename recovery. */\n clear(): void {\n this.cache.clear();\n }\n\n size(): number {\n return this.cache.size;\n }\n}\n","/**\n * Lazy `matrix-js-sdk` loader.\n */\n\nimport { SDKNotInstalledError } from \"./errors.js\";\nimport type { MatrixClientLike } from \"./sync.js\";\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport interface MatrixSdkClient extends MatrixClientLike {\n startClient(opts: { initialSyncLimit: number }): Promise<void>;\n stopClient(): void;\n sendTextMessage(roomId: string, text: string): Promise<{ event_id: string }>;\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n getRoom(roomId: string): MatrixRoomLike | null;\n isRoomEncrypted?(roomId: string): boolean;\n /** Best-effort current user id; matrix-js-sdk returns `string | null`. */\n getUserId(): string | null;\n /**\n * `/_matrix/client/v3/account/whoami` — the cheapest call that makes the\n * server judge the access token. `startClient` does not: it begins syncing\n * asynchronously and resolves regardless, so without this an invalid token\n * produces a connected-looking adapter that never receives anything.\n */\n whoami(): Promise<{ user_id: string }>;\n}\n\ninterface MatrixSdkModule {\n createClient(opts: { baseUrl: string; accessToken: string; userId: string }): MatrixSdkClient;\n}\n\nexport async function loadMatrixSdk(): Promise<MatrixSdkModule> {\n try {\n const mod = await import(\"matrix-js-sdk\");\n return mod as unknown as MatrixSdkModule;\n } catch {\n throw new SDKNotInstalledError();\n }\n}\n","/**\n * Room state helpers (D416).\n *\n * Matrix has no native \"DM\" concept — DMs are rooms with 2 members.\n * The canonical heuristic: `member_count === 2 → \"dm\"`, else `\"group\"`.\n */\n\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport function detectChannelType(room: MatrixRoomLike | undefined): \"dm\" | \"group\" {\n if (room === undefined) return \"group\";\n return room.getJoinedMemberCount() === 2 ? \"dm\" : \"group\";\n}\n","/**\n * Inbound normalization: MatrixEvent + Room → MatrixMessageEvent.\n *\n * @public\n */\n\nimport type { MatrixMessageEvent } from \"@theokit/gateway\";\n\nimport { detectChannelType } from \"./room-state.js\";\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport function matrixEventToMessageEvent(\n event: MatrixEventLike,\n room: MatrixRoomLike,\n): MatrixMessageEvent | undefined {\n const eventId = event.getId();\n const sender = event.getSender();\n if (eventId === undefined || sender === undefined) return undefined;\n const channelType = detectChannelType(room);\n const content = event.getContent();\n const body = content.body ?? \"\";\n return {\n id: eventId,\n platform: \"matrix\",\n sender: { id: sender },\n channel: {\n id: room.roomId,\n type: channelType,\n },\n text: body,\n receivedAt: event.getTs(),\n matrix: {\n roomId: room.roomId,\n eventId,\n memberCount: room.getJoinedMemberCount(),\n raw: event,\n },\n };\n}\n","/**\n * Sync timeline filter (D415, EC-3 absorbed).\n *\n * Wraps `client.on(\"Room.timeline\", listener)` with 3 filters:\n *\n * 1. Drop non-`m.room.message` events (D413).\n * 2. Drop bot's own messages (loop guard, D275 mirror).\n * 3. **EC-3**: drop events older than `freshnessWindowMs` (default 60s)\n * — initial sync from `matrix-js-sdk` delivers ~10 historical events\n * per joined room, which would otherwise trigger an LLM-call storm.\n */\n\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport interface SyncFilterOpts {\n readonly botUserId: string;\n readonly freshnessWindowMs: number;\n}\n\n/**\n * Decide whether a timeline event should reach the handler.\n *\n * Matrix replays room history on sync, so a freshly started bot would otherwise answer every message\n * it can still see — which is a reply storm in a busy room and an infinite loop in a quiet one. This\n * drops the bot's own events and anything older than the freshness window. `now` is injectable so\n * the decision is testable without waiting.\n */\nexport function shouldDispatchSyncEvent(\n event: MatrixEventLike,\n opts: SyncFilterOpts,\n now = Date.now(),\n): boolean {\n if (event.getType() !== \"m.room.message\") return false;\n const sender = event.getSender();\n if (sender === opts.botUserId) return false;\n if (event.getTs() < now - opts.freshnessWindowMs) return false;\n return true;\n}\n\n/** A live timeline listener, with the handle that detaches it again. */\nexport interface TimelineSubscription {\n unsubscribe(): void;\n}\n\n/**\n * The slice of `matrix-js-sdk`'s client this adapter actually uses.\n *\n * Narrow on purpose: it is what lets the sync logic be tested against a few lines of fake rather\n * than a running homeserver, and it states the real coupling to the SDK — two event methods.\n */\nexport interface MatrixClientLike {\n on(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n off(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n}\n\n/**\n * Attach `handler` to the client's room timeline, filtered by {@link shouldDispatchSyncEvent}.\n *\n * Returns the subscription rather than leaving the listener attached forever: an adapter that\n * reconnects without detaching accumulates listeners, and every inbound message is then handled\n * once per reconnect.\n */\nexport function subscribeToTimeline(\n client: MatrixClientLike,\n handler: (event: MatrixEventLike, room: MatrixRoomLike) => void,\n opts: SyncFilterOpts,\n): TimelineSubscription {\n const wrapped = (event: MatrixEventLike, room: MatrixRoomLike): void => {\n if (!shouldDispatchSyncEvent(event, opts)) return;\n handler(event, room);\n };\n client.on(\"Room.timeline\", wrapped);\n return {\n unsubscribe(): void {\n client.off(\"Room.timeline\", wrapped);\n },\n };\n}\n","/**\n * `MatrixAdapter` — implements BasePlatformAdapter over matrix-js-sdk.\n * ADRs D413-D421.\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 { AliasCache } from \"./alias.js\";\nimport { loadMatrixSdk, type MatrixSdkClient } from \"./client.js\";\nimport { ConfigurationError } from \"./errors.js\";\nimport { matrixEventToMessageEvent } from \"./normalize.js\";\nimport { subscribeToTimeline, type TimelineSubscription } from \"./sync.js\";\nimport type { MatrixAdapterOptions, MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nconst DEFAULT_FRESHNESS_MS = 60_000;\nconst INITIAL_SYNC_LIMIT = 10;\n\nexport class MatrixAdapter extends BasePlatformAdapter {\n readonly platform = \"matrix\" as const;\n private readonly opts: MatrixAdapterOptions;\n private client: MatrixSdkClient | undefined;\n private subscription: TimelineSubscription | undefined;\n private inboundHandler: ((event: GatewayMessageEvent) => Promise<void>) | undefined;\n private readonly aliasCache = new AliasCache();\n private connected = false;\n private readonly warnedEncrypted = new Set<string>();\n /** True only between disconnect() and the next connect() — see #12. */\n private tearingDown = false;\n\n /**\n * `fetch` for the SDK that leaves teardown aborts unsettled instead of\n * rejecting (#12).\n *\n * A request aborted while we are tearing the client down has no consumer left\n * that could act on the outcome, so an unsettled promise costs a continuation\n * and nothing else; the alternative is a rejection with no handler anywhere,\n * which ends the host process. It is scoped to the teardown window on purpose:\n * a consumer using the `getClient()` escape hatch (D421) may pass its own\n * abort signal to `search()` or `slidingSync()` and MUST still see those\n * rejections, so outside teardown every error propagates untouched.\n */\n private teardownSafeFetch(): typeof globalThis.fetch {\n const base = globalThis.fetch.bind(globalThis);\n return (input, init) =>\n base(input, init).catch((err: unknown) => {\n if (this.tearingDown && isAbortError(err)) {\n return new Promise<Response>(() => {\n /* deliberately never settles — see the doc comment */\n });\n }\n throw err;\n });\n }\n\n constructor(opts: MatrixAdapterOptions) {\n super();\n if (opts.homeserverUrl.length === 0) {\n throw new ConfigurationError({\n code: \"homeserver_url_required\",\n message: 'gateway-matrix: opts.homeserverUrl is empty (e.g. \"https://matrix.org\")',\n });\n }\n if (opts.accessToken.length === 0) {\n throw new ConfigurationError({\n code: \"access_token_required\",\n message:\n \"gateway-matrix: opts.accessToken is empty (Element → Settings → Help & About → Advanced → Access Token)\",\n });\n }\n if (opts.userId.length === 0 || !opts.userId.startsWith(\"@\")) {\n throw new ConfigurationError({\n code: \"user_id_required\",\n message: 'gateway-matrix: opts.userId must be a Matrix user id (e.g. \"@bot:matrix.org\")',\n });\n }\n this.opts = opts;\n }\n\n async connect(): Promise<boolean> {\n if (this.connected) return true;\n this.tearingDown = false;\n try {\n const cfg = {\n baseUrl: this.opts.homeserverUrl,\n accessToken: this.opts.accessToken,\n userId: this.opts.userId,\n fetchFn: this.teardownSafeFetch(),\n };\n const factory = this.opts.__clientFactory;\n this.client =\n factory === undefined\n ? (await loadMatrixSdk()).createClient(cfg)\n : (factory(cfg) as MatrixSdkClient);\n // Validate the credential BEFORE reporting success. `startClient` kicks\n // off the sync loop asynchronously and resolves whether or not the token\n // is any good — so connect() used to answer `true` for a token the server\n // rejects, leaving an operator with a healthy-looking adapter and total\n // silence. Every sibling adapter returns false here; this one did not,\n // and only a real homeserver could show it.\n await this.client.whoami();\n await this.client.startClient({ initialSyncLimit: INITIAL_SYNC_LIMIT });\n this.attachSync();\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-matrix] connect failed: ${msg}\\n`);\n return false;\n }\n }\n\n async disconnect(): Promise<void> {\n if (!this.connected) return;\n // Issue #12. `stopClient()` aborts the requests still in flight, and the\n // AbortError escapes as an UNHANDLED rejection — the rejecting promise is\n // the SDK's own `authedRequest` wrapper, which no caller catches and which\n // we cannot reach. Node has terminated on unhandled rejections by default\n // since v15, so an application calling disconnect() inside a reconnect loop\n // could be killed by its own clean shutdown. Measured against a real\n // homeserver: 7 occurrences in 8 connect/disconnect cycles.\n //\n // `teardownSafeFetch` closes it at the only seam the SDK offers. The flag is\n // set here, before the abort, and cleared by the next connect().\n this.tearingDown = true;\n this.subscription?.unsubscribe();\n this.subscription = undefined;\n this.client?.stopClient();\n this.client = undefined;\n this.connected = false;\n this.inboundHandler = undefined;\n this.aliasCache.clear();\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.client === undefined) {\n return {\n ok: false,\n error: { code: \"not_connected\", message: \"MatrixAdapter.connect() not called\" },\n };\n }\n try {\n const roomId = await this.aliasCache.resolve(this.client, out.channel.id);\n if (this.isEncrypted(roomId)) {\n this.warnEncryptedOnce(roomId);\n return {\n ok: false,\n error: {\n code: \"encrypted_room_unsupported\",\n message: `Matrix room ${roomId} is encrypted; E2EE deferred to v0.2`,\n },\n };\n }\n const res = await this.client.sendTextMessage(roomId, out.text);\n return { ok: true, messageId: res.event_id };\n } catch (err) {\n return mapMatrixError(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 (D421) — caller can drive matrix-js-sdk directly for advanced features. */\n getClient(): MatrixSdkClient | undefined {\n return this.client;\n }\n\n /** Used by tests to install a mock SDK client + flip connected flag. */\n _installClient(client: MatrixSdkClient): void {\n this.client = client;\n this.connected = true;\n this.attachSync();\n }\n\n private attachSync(): void {\n if (this.client === undefined) return;\n const client = this.client;\n const opts = {\n botUserId: this.opts.userId,\n freshnessWindowMs: this.opts.freshnessWindowMs ?? DEFAULT_FRESHNESS_MS,\n };\n this.subscription = subscribeToTimeline(\n client,\n (ev: MatrixEventLike, room: MatrixRoomLike) => {\n void this.dispatchTimelineEvent(ev, room).catch((err: unknown) => {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] dispatchTimelineEvent failed: ${m}\\n`);\n });\n },\n opts,\n );\n }\n\n private async dispatchTimelineEvent(event: MatrixEventLike, room: MatrixRoomLike): Promise<void> {\n if (this.isEncrypted(room.roomId)) {\n this.warnEncryptedOnce(room.roomId);\n return;\n }\n const normalized = matrixEventToMessageEvent(event, room);\n if (normalized === undefined) return;\n if (this.inboundHandler === undefined) return;\n try {\n await this.inboundHandler(normalized);\n } catch (err) {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] handler threw: ${m}\\n`);\n }\n }\n\n private isEncrypted(roomId: string): boolean {\n if (this.client === undefined) return false;\n if (this.client.isRoomEncrypted === undefined) return false;\n try {\n return this.client.isRoomEncrypted(roomId);\n } catch {\n return false;\n }\n }\n\n private warnEncryptedOnce(roomId: string): void {\n if (this.warnedEncrypted.has(roomId)) return;\n this.warnedEncrypted.add(roomId);\n process.stderr.write(\n `[gateway-matrix] room ${roomId} is end-to-end encrypted; skipping (E2EE deferred to v0.2)\\n`,\n );\n }\n}\n\n/**\n * Narrow abort detection. `DOMException.ABORT_ERR` is 20; the message check\n * covers runtimes that report the abort without the standard name or code.\n */\nfunction isAbortError(err: unknown): boolean {\n if (typeof err !== \"object\" || err === null) return false;\n const e = err as { name?: unknown; code?: unknown; message?: unknown };\n if (e.name === \"AbortError\") return true;\n if (e.code === 20) return true;\n return typeof e.message === \"string\" && /aborted/i.test(e.message);\n}\n\ninterface MatrixRestError {\n httpStatus?: number;\n errcode?: string;\n message?: string;\n name?: string;\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: error mapping ladder is exhaustive — each branch maps one Matrix errcode/HTTP status to one canonical code; splitting hurts traceability.\nfunction mapMatrixError(err: unknown): SendResult {\n const e = err as MatrixRestError;\n const status = e.httpStatus ?? 0;\n if (status === 429 || e.errcode === \"M_LIMIT_EXCEEDED\") {\n return { ok: false, error: { code: \"rate_limit\", message: e.message ?? \"Matrix rate limit\" } };\n }\n if (status === 401 || status === 403 || e.errcode === \"M_FORBIDDEN\") {\n return {\n ok: false,\n error: { code: \"permission_denied\", message: e.message ?? \"Matrix permission error\" },\n };\n }\n if (status === 404 || e.errcode === \"M_NOT_FOUND\") {\n return {\n ok: false,\n error: { code: \"not_found\", message: e.message ?? \"Matrix resource not found\" },\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"]}
|
|
1
|
+
{"version":3,"sources":["../src/errors.ts","../src/alias.ts","../src/client.ts","../src/room-state.ts","../src/normalize.ts","../src/sync.ts","../src/adapter.ts"],"names":["GatewayConfigurationError","BasePlatformAdapter"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Typed errors for `@theokit/gateway-matrix`.\n *\n * `ConfigurationError` extends the shared core `GatewayConfigurationError`\n * base (roadmap M2). Behavior byte-identical (pinned by `tests/errors.test.ts`).\n */\n\nimport { GatewayConfigurationError, type GatewayConfigurationErrorOptions } from \"@theokit/gateway\";\n\n/** @knipignore — public input shape for `ConfigurationError` constructor (caller-extensible). */\nexport type ConfigurationErrorOptions = GatewayConfigurationErrorOptions;\n\n/**\n * Misconfiguration of this adapter, raised before any network call.\n *\n * Extends the shared core base so every gateway package reports configuration faults in one shape:\n * a structured `code` the caller can branch on, tagged with `\"gateway-matrix\"` as the origin. A\n * missing credential or an unsupported option is a programmer error, not a transient failure —\n * these are never retried.\n */\nexport class ConfigurationError extends GatewayConfigurationError {\n override readonly name = \"ConfigurationError\";\n constructor(opts: ConfigurationErrorOptions) {\n super(\"gateway-matrix\", opts);\n }\n}\n\n/**\n * The platform SDK this adapter needs is declared as a peer dependency and is not installed.\n *\n * Raised at connect time rather than at import, so a project that installs several gateway packages\n * only pays for the SDKs of the ones it actually starts. The message names the exact package and\n * the command that installs it.\n */\nexport class SDKNotInstalledError extends ConfigurationError {\n constructor() {\n super({\n code: \"sdk_not_installed\",\n message:\n 'gateway-matrix: peer-dep \"matrix-js-sdk\" not installed. Run: pnpm add matrix-js-sdk',\n detail: \"matrix-js-sdk\",\n });\n }\n}\n\n/**\n * The room is end-to-end encrypted, which this adapter cannot read.\n *\n * E2EE is deferred to v0.2. Raised rather than silently ignoring the room, because a bot that\n * appears connected and never sees a message is far harder to diagnose than one that says why.\n */\nexport class EncryptedRoomError extends ConfigurationError {\n constructor(roomId: string) {\n super({\n code: \"encrypted_room_unsupported\",\n message: `gateway-matrix: room ${roomId} is end-to-end encrypted (E2EE deferred to v0.2)`,\n detail: roomId,\n });\n }\n}\n","/**\n * Matrix alias resolution + caching (D419).\n *\n * Accepts:\n * - Room id (`!abc123:server`) — pass-through.\n * - Alias (`#general:server`) — resolved via `client.getRoomIdForAlias`.\n *\n * Other shapes throw `ConfigurationError({ code: \"invalid_room_ref\" })`.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\n\n/** @knipignore — minimal Client interface `AliasCache.resolve` accepts; useful for callers building their own resolver. */\nexport interface AliasResolverClient {\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n}\n\n/**\n * Resolves a Matrix room alias (`#room:server`) to its room id, remembering the answer.\n *\n * An alias resolves through a server round-trip, and the mapping effectively never changes, so\n * repeating it once per outbound message is pure latency. A value that is already a room id is\n * returned untouched, which lets callers pass either form.\n */\nexport class AliasCache {\n private readonly cache = new Map<string, string>();\n\n /** Returns the room id; resolves aliases via the client + caches. */\n async resolve(client: AliasResolverClient, refOrId: string): Promise<string> {\n if (refOrId.startsWith(\"!\")) return refOrId;\n if (!refOrId.startsWith(\"#\")) {\n throw new ConfigurationError({\n code: \"invalid_room_ref\",\n message: `gateway-matrix: invalid room reference ${JSON.stringify(refOrId)} — expected '!' (room id) or '#' (alias)`,\n });\n }\n const cached = this.cache.get(refOrId);\n if (cached !== undefined) return cached;\n const { room_id } = await client.getRoomIdForAlias(refOrId);\n this.cache.set(refOrId, room_id);\n return room_id;\n }\n\n /** Drop all cached resolutions. Useful for tests + admin-rename recovery. */\n clear(): void {\n this.cache.clear();\n }\n\n size(): number {\n return this.cache.size;\n }\n}\n","/**\n * Lazy `matrix-js-sdk` loader.\n */\n\nimport { SDKNotInstalledError } from \"./errors.js\";\nimport type { MatrixClientLike } from \"./sync.js\";\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport interface MatrixSdkClient extends MatrixClientLike {\n startClient(opts: { initialSyncLimit: number }): Promise<void>;\n stopClient(): void;\n sendTextMessage(roomId: string, text: string): Promise<{ event_id: string }>;\n /**\n * Send a message whose content object the caller composes.\n *\n * `sendTextMessage` is a convenience that hard-codes `msgtype: m.text` and a bare `body`, so\n * it has nowhere to put `formatted_body` — the field Matrix documents for markup. Honouring\n * `OutboundMessage.format` therefore needs the general call, not a new argument on the\n * convenience one.\n */\n sendMessage?(roomId: string, content: Record<string, unknown>): Promise<{ event_id: string }>;\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n getRoom(roomId: string): MatrixRoomLike | null;\n isRoomEncrypted?(roomId: string): boolean;\n /** Best-effort current user id; matrix-js-sdk returns `string | null`. */\n getUserId(): string | null;\n /**\n * `/_matrix/client/v3/account/whoami` — the cheapest call that makes the\n * server judge the access token. `startClient` does not: it begins syncing\n * asynchronously and resolves regardless, so without this an invalid token\n * produces a connected-looking adapter that never receives anything.\n */\n whoami(): Promise<{ user_id: string }>;\n}\n\ninterface MatrixSdkModule {\n createClient(opts: { baseUrl: string; accessToken: string; userId: string }): MatrixSdkClient;\n}\n\nexport async function loadMatrixSdk(): Promise<MatrixSdkModule> {\n try {\n const mod = await import(\"matrix-js-sdk\");\n return mod as unknown as MatrixSdkModule;\n } catch {\n throw new SDKNotInstalledError();\n }\n}\n","/**\n * Room state helpers (D416).\n *\n * Matrix has no native \"DM\" concept — DMs are rooms with 2 members.\n * The canonical heuristic: `member_count === 2 → \"dm\"`, else `\"group\"`.\n */\n\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport function detectChannelType(room: MatrixRoomLike | undefined): \"dm\" | \"group\" {\n if (room === undefined) return \"group\";\n return room.getJoinedMemberCount() === 2 ? \"dm\" : \"group\";\n}\n","/**\n * Inbound normalization: MatrixEvent + Room → MatrixMessageEvent.\n *\n * @public\n */\n\nimport type { MatrixMessageEvent } from \"@theokit/gateway\";\n\nimport { detectChannelType } from \"./room-state.js\";\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport function matrixEventToMessageEvent(\n event: MatrixEventLike,\n room: MatrixRoomLike,\n): MatrixMessageEvent | undefined {\n const eventId = event.getId();\n const sender = event.getSender();\n if (eventId === undefined || sender === undefined) return undefined;\n const channelType = detectChannelType(room);\n const content = event.getContent();\n const body = content.body ?? \"\";\n return {\n id: eventId,\n platform: \"matrix\",\n sender: { id: sender },\n channel: {\n id: room.roomId,\n type: channelType,\n },\n text: body,\n receivedAt: event.getTs(),\n matrix: {\n roomId: room.roomId,\n eventId,\n memberCount: room.getJoinedMemberCount(),\n raw: event,\n },\n };\n}\n","/**\n * Sync timeline filter (D415, EC-3 absorbed).\n *\n * Wraps `client.on(\"Room.timeline\", listener)` with 3 filters:\n *\n * 1. Drop non-`m.room.message` events (D413).\n * 2. Drop bot's own messages (loop guard, D275 mirror).\n * 3. **EC-3**: drop events older than `freshnessWindowMs` (default 60s)\n * — initial sync from `matrix-js-sdk` delivers ~10 historical events\n * per joined room, which would otherwise trigger an LLM-call storm.\n */\n\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport interface SyncFilterOpts {\n readonly botUserId: string;\n readonly freshnessWindowMs: number;\n}\n\n/**\n * Decide whether a timeline event should reach the handler.\n *\n * Matrix replays room history on sync, so a freshly started bot would otherwise answer every message\n * it can still see — which is a reply storm in a busy room and an infinite loop in a quiet one. This\n * drops the bot's own events and anything older than the freshness window. `now` is injectable so\n * the decision is testable without waiting.\n */\nexport function shouldDispatchSyncEvent(\n event: MatrixEventLike,\n opts: SyncFilterOpts,\n now = Date.now(),\n): boolean {\n if (event.getType() !== \"m.room.message\") return false;\n const sender = event.getSender();\n if (sender === opts.botUserId) return false;\n if (event.getTs() < now - opts.freshnessWindowMs) return false;\n return true;\n}\n\n/** A live timeline listener, with the handle that detaches it again. */\nexport interface TimelineSubscription {\n unsubscribe(): void;\n}\n\n/**\n * The slice of `matrix-js-sdk`'s client this adapter actually uses.\n *\n * Narrow on purpose: it is what lets the sync logic be tested against a few lines of fake rather\n * than a running homeserver, and it states the real coupling to the SDK — two event methods.\n */\nexport interface MatrixClientLike {\n on(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n off(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n}\n\n/**\n * Attach `handler` to the client's room timeline, filtered by {@link shouldDispatchSyncEvent}.\n *\n * Returns the subscription rather than leaving the listener attached forever: an adapter that\n * reconnects without detaching accumulates listeners, and every inbound message is then handled\n * once per reconnect.\n */\nexport function subscribeToTimeline(\n client: MatrixClientLike,\n handler: (event: MatrixEventLike, room: MatrixRoomLike) => void,\n opts: SyncFilterOpts,\n): TimelineSubscription {\n const wrapped = (event: MatrixEventLike, room: MatrixRoomLike): void => {\n if (!shouldDispatchSyncEvent(event, opts)) return;\n handler(event, room);\n };\n client.on(\"Room.timeline\", wrapped);\n return {\n unsubscribe(): void {\n client.off(\"Room.timeline\", wrapped);\n },\n };\n}\n","/**\n * `MatrixAdapter` — implements BasePlatformAdapter over matrix-js-sdk.\n * ADRs D413-D421.\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 { AliasCache } from \"./alias.js\";\nimport { loadMatrixSdk, type MatrixSdkClient } from \"./client.js\";\nimport { ConfigurationError } from \"./errors.js\";\nimport { matrixEventToMessageEvent } from \"./normalize.js\";\nimport { subscribeToTimeline, type TimelineSubscription } from \"./sync.js\";\nimport type { MatrixAdapterOptions, MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nconst DEFAULT_FRESHNESS_MS = 60_000;\nconst INITIAL_SYNC_LIMIT = 10;\n\nexport class MatrixAdapter extends BasePlatformAdapter {\n readonly platform = \"matrix\" as const;\n private readonly opts: MatrixAdapterOptions;\n private client: MatrixSdkClient | undefined;\n private subscription: TimelineSubscription | undefined;\n private inboundHandler: ((event: GatewayMessageEvent) => Promise<void>) | undefined;\n private readonly aliasCache = new AliasCache();\n private connected = false;\n private readonly warnedEncrypted = new Set<string>();\n /** True only between disconnect() and the next connect() — see #12. */\n private tearingDown = false;\n\n /**\n * `fetch` for the SDK that leaves teardown aborts unsettled instead of\n * rejecting (#12).\n *\n * A request aborted while we are tearing the client down has no consumer left\n * that could act on the outcome, so an unsettled promise costs a continuation\n * and nothing else; the alternative is a rejection with no handler anywhere,\n * which ends the host process. It is scoped to the teardown window on purpose:\n * a consumer using the `getClient()` escape hatch (D421) may pass its own\n * abort signal to `search()` or `slidingSync()` and MUST still see those\n * rejections, so outside teardown every error propagates untouched.\n */\n private teardownSafeFetch(): typeof globalThis.fetch {\n const base = globalThis.fetch.bind(globalThis);\n return (input, init) =>\n base(input, init).catch((err: unknown) => {\n if (this.tearingDown && isAbortError(err)) {\n return new Promise<Response>(() => {\n /* deliberately never settles — see the doc comment */\n });\n }\n throw err;\n });\n }\n\n constructor(opts: MatrixAdapterOptions) {\n super();\n if (opts.homeserverUrl.length === 0) {\n throw new ConfigurationError({\n code: \"homeserver_url_required\",\n message: 'gateway-matrix: opts.homeserverUrl is empty (e.g. \"https://matrix.org\")',\n });\n }\n if (opts.accessToken.length === 0) {\n throw new ConfigurationError({\n code: \"access_token_required\",\n message:\n \"gateway-matrix: opts.accessToken is empty (Element → Settings → Help & About → Advanced → Access Token)\",\n });\n }\n if (opts.userId.length === 0 || !opts.userId.startsWith(\"@\")) {\n throw new ConfigurationError({\n code: \"user_id_required\",\n message: 'gateway-matrix: opts.userId must be a Matrix user id (e.g. \"@bot:matrix.org\")',\n });\n }\n this.opts = opts;\n }\n\n async connect(): Promise<boolean> {\n if (this.connected) return true;\n this.tearingDown = false;\n try {\n const cfg = {\n baseUrl: this.opts.homeserverUrl,\n accessToken: this.opts.accessToken,\n userId: this.opts.userId,\n fetchFn: this.teardownSafeFetch(),\n };\n const factory = this.opts.__clientFactory;\n this.client =\n factory === undefined\n ? (await loadMatrixSdk()).createClient(cfg)\n : (factory(cfg) as MatrixSdkClient);\n // Validate the credential BEFORE reporting success. `startClient` kicks\n // off the sync loop asynchronously and resolves whether or not the token\n // is any good — so connect() used to answer `true` for a token the server\n // rejects, leaving an operator with a healthy-looking adapter and total\n // silence. Every sibling adapter returns false here; this one did not,\n // and only a real homeserver could show it.\n await this.client.whoami();\n await this.client.startClient({ initialSyncLimit: INITIAL_SYNC_LIMIT });\n this.attachSync();\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-matrix] connect failed: ${msg}\\n`);\n return false;\n }\n }\n\n async disconnect(): Promise<void> {\n if (!this.connected) return;\n // Issue #12. `stopClient()` aborts the requests still in flight, and the\n // AbortError escapes as an UNHANDLED rejection — the rejecting promise is\n // the SDK's own `authedRequest` wrapper, which no caller catches and which\n // we cannot reach. Node has terminated on unhandled rejections by default\n // since v15, so an application calling disconnect() inside a reconnect loop\n // could be killed by its own clean shutdown. Measured against a real\n // homeserver: 7 occurrences in 8 connect/disconnect cycles.\n //\n // `teardownSafeFetch` closes it at the only seam the SDK offers. The flag is\n // set here, before the abort, and cleared by the next connect().\n this.tearingDown = true;\n this.subscription?.unsubscribe();\n this.subscription = undefined;\n this.client?.stopClient();\n this.client = undefined;\n this.connected = false;\n this.inboundHandler = undefined;\n this.aliasCache.clear();\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.client === undefined) {\n return {\n ok: false,\n error: { code: \"not_connected\", message: \"MatrixAdapter.connect() not called\" },\n };\n }\n try {\n const roomId = await this.aliasCache.resolve(this.client, out.channel.id);\n if (this.isEncrypted(roomId)) {\n this.warnEncryptedOnce(roomId);\n return {\n ok: false,\n error: {\n code: \"encrypted_room_unsupported\",\n message: `Matrix room ${roomId} is encrypted; E2EE deferred to v0.2`,\n },\n };\n }\n const res = await this.sendHonouringFormat(roomId, out);\n return { ok: true, messageId: res.event_id };\n } catch (err) {\n return mapMatrixError(err);\n }\n }\n\n /**\n * Send `out`, letting the caller's declared `format` decide the shape.\n *\n * Matrix carries markup in `formatted_body` and declares its type in `format`, whose only\n * value is `org.matrix.custom.html`. That declaration is a promise to every client that the\n * field IS HTML — so only `format: \"html\"` may use it.\n *\n * **`markdown` deliberately does not.** The first version of this method put the caller's\n * markdown into `formatted_body` and declared it HTML, which was worse than the bug it meant\n * to fix: `**bold**` still rendered as literal asterisks because markdown is not HTML, AND a\n * `<div>` anywhere in the text was parsed as a tag and dropped, so the reader received words\n * the sender never wrote and lost the ones they did. Caught in review; the test that\n * \"proved\" it was asserting the defect.\n *\n * So Matrix joins LINE, SMS and WhatsApp: it has no markdown mode, and the honest handling is\n * to say once that the declaration is being dropped rather than to fake it.\n *\n * Falls back to `sendTextMessage` when the client does not expose `sendMessage`: it is\n * optional on {@link MatrixSdkClient} because a consumer may inject a narrower double, and\n * losing the formatting is better than losing the message.\n *\n * @internal\n */\n private async sendHonouringFormat(\n roomId: string,\n out: OutboundMessage,\n ): Promise<{ event_id: string }> {\n const client = this.client as MatrixSdkClient;\n if (out.format !== \"html\" || client.sendMessage === undefined) {\n this.warnFormatUnsupported(out.format);\n return await client.sendTextMessage(roomId, out.text);\n }\n try {\n return await client.sendMessage(roomId, {\n msgtype: \"m.text\",\n body: out.text,\n format: \"org.matrix.custom.html\",\n formatted_body: out.text,\n });\n } catch (err) {\n // ADR-2: an undelivered message is worse than an unformatted one — the caller loses the\n // content and the user sees nothing, which is strictly worse than losing the markup.\n //\n // The discrimination is the whole guard. A bare `catch` would swallow an expired token as\n // a formatting problem and retry into the same 401, turning an actionable error into a\n // silent double failure. Only a request the server judged malformed is retried.\n if (!isMalformedRequest(err)) throw err;\n process.stderr.write(\n \"[gateway-matrix] homeserver rejected the formatted body; retrying as plain text\\n\",\n );\n return await client.sendTextMessage(roomId, out.text);\n }\n }\n\n /** Whether the \"no markdown mode here\" warning has already been emitted. */\n private warnedAboutFormat = false;\n\n /**\n * Say, once, that a declared `markdown` has nowhere to go on this platform.\n *\n * Matrix's only markup type is HTML. A caller declaring `markdown` is asking for something\n * the protocol does not have, and putting the markdown in the HTML field would corrupt it.\n *\n * @internal\n */\n private warnFormatUnsupported(format: OutboundMessage[\"format\"]): void {\n if (format === undefined || format === \"plain\" || format === \"html\") return;\n if (this.warnedAboutFormat) return;\n this.warnedAboutFormat = true;\n process.stderr.write(\n `[gateway-matrix] format=\"${format}\" was declared, and Matrix has no markdown mode — ` +\n \"its only markup type is HTML. Sending as plain text; this is logged once.\\n\",\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 (D421) — caller can drive matrix-js-sdk directly for advanced features. */\n getClient(): MatrixSdkClient | undefined {\n return this.client;\n }\n\n /** Used by tests to install a mock SDK client + flip connected flag. */\n _installClient(client: MatrixSdkClient): void {\n this.client = client;\n this.connected = true;\n this.attachSync();\n }\n\n private attachSync(): void {\n if (this.client === undefined) return;\n const client = this.client;\n const opts = {\n botUserId: this.opts.userId,\n freshnessWindowMs: this.opts.freshnessWindowMs ?? DEFAULT_FRESHNESS_MS,\n };\n this.subscription = subscribeToTimeline(\n client,\n (ev: MatrixEventLike, room: MatrixRoomLike) => {\n void this.dispatchTimelineEvent(ev, room).catch((err: unknown) => {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] dispatchTimelineEvent failed: ${m}\\n`);\n });\n },\n opts,\n );\n }\n\n private async dispatchTimelineEvent(event: MatrixEventLike, room: MatrixRoomLike): Promise<void> {\n if (this.isEncrypted(room.roomId)) {\n this.warnEncryptedOnce(room.roomId);\n return;\n }\n const normalized = matrixEventToMessageEvent(event, room);\n if (normalized === undefined) return;\n if (this.inboundHandler === undefined) return;\n try {\n await this.inboundHandler(normalized);\n } catch (err) {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] handler threw: ${m}\\n`);\n }\n }\n\n private isEncrypted(roomId: string): boolean {\n if (this.client === undefined) return false;\n if (this.client.isRoomEncrypted === undefined) return false;\n try {\n return this.client.isRoomEncrypted(roomId);\n } catch {\n return false;\n }\n }\n\n private warnEncryptedOnce(roomId: string): void {\n if (this.warnedEncrypted.has(roomId)) return;\n this.warnedEncrypted.add(roomId);\n process.stderr.write(\n `[gateway-matrix] room ${roomId} is end-to-end encrypted; skipping (E2EE deferred to v0.2)\\n`,\n );\n }\n\n /**\n * Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).\n *\n * One line over `runHandler`, which owns the containment: a handler is user code, its throw is\n * named as the handler's failure rather than the platform's, and delivery continues.\n */\n override async deliver(\n event: GatewayMessageEvent,\n ): Promise<\"ok\" | \"no_handler\" | \"handler_threw\"> {\n return this.runHandler(this.inboundHandler, event);\n }\n}\n\n/**\n * Narrow abort detection. `DOMException.ABORT_ERR` is 20; the message check\n * covers runtimes that report the abort without the standard name or code.\n */\nfunction isAbortError(err: unknown): boolean {\n if (typeof err !== \"object\" || err === null) return false;\n const e = err as { name?: unknown; code?: unknown; message?: unknown };\n if (e.name === \"AbortError\") return true;\n if (e.code === 20) return true;\n return typeof e.message === \"string\" && /aborted/i.test(e.message);\n}\n\ninterface MatrixRestError {\n httpStatus?: number;\n errcode?: string;\n message?: string;\n name?: string;\n}\n\n/**\n * Did the homeserver judge the REQUEST malformed, as opposed to refusing the sender?\n *\n * Narrow by construction: a 400 with `M_BAD_JSON` or `M_INVALID_PARAM` is the server saying it\n * could not parse what it was given. A 401, 403 or 429 is about who is asking or how often,\n * and retrying those without markup would fail identically while reporting the wrong cause.\n */\nfunction isMalformedRequest(err: unknown): boolean {\n const e = err as MatrixRestError;\n if (e.httpStatus !== 400) return false;\n return e.errcode === \"M_BAD_JSON\" || e.errcode === \"M_INVALID_PARAM\";\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: error mapping ladder is exhaustive — each branch maps one Matrix errcode/HTTP status to one canonical code; splitting hurts traceability.\nfunction mapMatrixError(err: unknown): SendResult {\n const e = err as MatrixRestError;\n const status = e.httpStatus ?? 0;\n if (status === 429 || e.errcode === \"M_LIMIT_EXCEEDED\") {\n return { ok: false, error: { code: \"rate_limit\", message: e.message ?? \"Matrix rate limit\" } };\n }\n if (status === 401 || status === 403 || e.errcode === \"M_FORBIDDEN\") {\n return {\n ok: false,\n error: { code: \"permission_denied\", message: e.message ?? \"Matrix permission error\" },\n };\n }\n if (status === 404 || e.errcode === \"M_NOT_FOUND\") {\n return {\n ok: false,\n error: { code: \"not_found\", message: e.message ?? \"Matrix resource not found\" },\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"]}
|
package/dist/index.d.cts
CHANGED
|
@@ -114,6 +114,17 @@ interface MatrixSdkClient extends MatrixClientLike {
|
|
|
114
114
|
sendTextMessage(roomId: string, text: string): Promise<{
|
|
115
115
|
event_id: string;
|
|
116
116
|
}>;
|
|
117
|
+
/**
|
|
118
|
+
* Send a message whose content object the caller composes.
|
|
119
|
+
*
|
|
120
|
+
* `sendTextMessage` is a convenience that hard-codes `msgtype: m.text` and a bare `body`, so
|
|
121
|
+
* it has nowhere to put `formatted_body` — the field Matrix documents for markup. Honouring
|
|
122
|
+
* `OutboundMessage.format` therefore needs the general call, not a new argument on the
|
|
123
|
+
* convenience one.
|
|
124
|
+
*/
|
|
125
|
+
sendMessage?(roomId: string, content: Record<string, unknown>): Promise<{
|
|
126
|
+
event_id: string;
|
|
127
|
+
}>;
|
|
117
128
|
getRoomIdForAlias(alias: string): Promise<{
|
|
118
129
|
room_id: string;
|
|
119
130
|
}>;
|
|
@@ -167,6 +178,8 @@ declare class MatrixAdapter extends BasePlatformAdapter {
|
|
|
167
178
|
connect(): Promise<boolean>;
|
|
168
179
|
disconnect(): Promise<void>;
|
|
169
180
|
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
181
|
+
/** Whether the "no markdown mode here" warning has already been emitted. */
|
|
182
|
+
private warnedAboutFormat;
|
|
170
183
|
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
171
184
|
/** Escape hatch (D421) — caller can drive matrix-js-sdk directly for advanced features. */
|
|
172
185
|
getClient(): MatrixSdkClient | undefined;
|
|
@@ -176,6 +189,13 @@ declare class MatrixAdapter extends BasePlatformAdapter {
|
|
|
176
189
|
private dispatchTimelineEvent;
|
|
177
190
|
private isEncrypted;
|
|
178
191
|
private warnEncryptedOnce;
|
|
192
|
+
/**
|
|
193
|
+
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
194
|
+
*
|
|
195
|
+
* One line over `runHandler`, which owns the containment: a handler is user code, its throw is
|
|
196
|
+
* named as the handler's failure rather than the platform's, and delivery continues.
|
|
197
|
+
*/
|
|
198
|
+
deliver(event: MessageEvent): Promise<"ok" | "no_handler" | "handler_threw">;
|
|
179
199
|
}
|
|
180
200
|
|
|
181
201
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -114,6 +114,17 @@ interface MatrixSdkClient extends MatrixClientLike {
|
|
|
114
114
|
sendTextMessage(roomId: string, text: string): Promise<{
|
|
115
115
|
event_id: string;
|
|
116
116
|
}>;
|
|
117
|
+
/**
|
|
118
|
+
* Send a message whose content object the caller composes.
|
|
119
|
+
*
|
|
120
|
+
* `sendTextMessage` is a convenience that hard-codes `msgtype: m.text` and a bare `body`, so
|
|
121
|
+
* it has nowhere to put `formatted_body` — the field Matrix documents for markup. Honouring
|
|
122
|
+
* `OutboundMessage.format` therefore needs the general call, not a new argument on the
|
|
123
|
+
* convenience one.
|
|
124
|
+
*/
|
|
125
|
+
sendMessage?(roomId: string, content: Record<string, unknown>): Promise<{
|
|
126
|
+
event_id: string;
|
|
127
|
+
}>;
|
|
117
128
|
getRoomIdForAlias(alias: string): Promise<{
|
|
118
129
|
room_id: string;
|
|
119
130
|
}>;
|
|
@@ -167,6 +178,8 @@ declare class MatrixAdapter extends BasePlatformAdapter {
|
|
|
167
178
|
connect(): Promise<boolean>;
|
|
168
179
|
disconnect(): Promise<void>;
|
|
169
180
|
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
181
|
+
/** Whether the "no markdown mode here" warning has already been emitted. */
|
|
182
|
+
private warnedAboutFormat;
|
|
170
183
|
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
171
184
|
/** Escape hatch (D421) — caller can drive matrix-js-sdk directly for advanced features. */
|
|
172
185
|
getClient(): MatrixSdkClient | undefined;
|
|
@@ -176,6 +189,13 @@ declare class MatrixAdapter extends BasePlatformAdapter {
|
|
|
176
189
|
private dispatchTimelineEvent;
|
|
177
190
|
private isEncrypted;
|
|
178
191
|
private warnEncryptedOnce;
|
|
192
|
+
/**
|
|
193
|
+
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
194
|
+
*
|
|
195
|
+
* One line over `runHandler`, which owns the containment: a handler is user code, its throw is
|
|
196
|
+
* named as the handler's failure rather than the platform's, and delivery continues.
|
|
197
|
+
*/
|
|
198
|
+
deliver(event: MessageEvent): Promise<"ok" | "no_handler" | "handler_threw">;
|
|
179
199
|
}
|
|
180
200
|
|
|
181
201
|
/**
|
package/dist/index.js
CHANGED
|
@@ -232,12 +232,75 @@ var MatrixAdapter = class extends BasePlatformAdapter {
|
|
|
232
232
|
}
|
|
233
233
|
};
|
|
234
234
|
}
|
|
235
|
-
const res = await this.
|
|
235
|
+
const res = await this.sendHonouringFormat(roomId, out);
|
|
236
236
|
return { ok: true, messageId: res.event_id };
|
|
237
237
|
} catch (err) {
|
|
238
238
|
return mapMatrixError(err);
|
|
239
239
|
}
|
|
240
240
|
}
|
|
241
|
+
/**
|
|
242
|
+
* Send `out`, letting the caller's declared `format` decide the shape.
|
|
243
|
+
*
|
|
244
|
+
* Matrix carries markup in `formatted_body` and declares its type in `format`, whose only
|
|
245
|
+
* value is `org.matrix.custom.html`. That declaration is a promise to every client that the
|
|
246
|
+
* field IS HTML — so only `format: "html"` may use it.
|
|
247
|
+
*
|
|
248
|
+
* **`markdown` deliberately does not.** The first version of this method put the caller's
|
|
249
|
+
* markdown into `formatted_body` and declared it HTML, which was worse than the bug it meant
|
|
250
|
+
* to fix: `**bold**` still rendered as literal asterisks because markdown is not HTML, AND a
|
|
251
|
+
* `<div>` anywhere in the text was parsed as a tag and dropped, so the reader received words
|
|
252
|
+
* the sender never wrote and lost the ones they did. Caught in review; the test that
|
|
253
|
+
* "proved" it was asserting the defect.
|
|
254
|
+
*
|
|
255
|
+
* So Matrix joins LINE, SMS and WhatsApp: it has no markdown mode, and the honest handling is
|
|
256
|
+
* to say once that the declaration is being dropped rather than to fake it.
|
|
257
|
+
*
|
|
258
|
+
* Falls back to `sendTextMessage` when the client does not expose `sendMessage`: it is
|
|
259
|
+
* optional on {@link MatrixSdkClient} because a consumer may inject a narrower double, and
|
|
260
|
+
* losing the formatting is better than losing the message.
|
|
261
|
+
*
|
|
262
|
+
* @internal
|
|
263
|
+
*/
|
|
264
|
+
async sendHonouringFormat(roomId, out) {
|
|
265
|
+
const client = this.client;
|
|
266
|
+
if (out.format !== "html" || client.sendMessage === void 0) {
|
|
267
|
+
this.warnFormatUnsupported(out.format);
|
|
268
|
+
return await client.sendTextMessage(roomId, out.text);
|
|
269
|
+
}
|
|
270
|
+
try {
|
|
271
|
+
return await client.sendMessage(roomId, {
|
|
272
|
+
msgtype: "m.text",
|
|
273
|
+
body: out.text,
|
|
274
|
+
format: "org.matrix.custom.html",
|
|
275
|
+
formatted_body: out.text
|
|
276
|
+
});
|
|
277
|
+
} catch (err) {
|
|
278
|
+
if (!isMalformedRequest(err)) throw err;
|
|
279
|
+
process.stderr.write(
|
|
280
|
+
"[gateway-matrix] homeserver rejected the formatted body; retrying as plain text\n"
|
|
281
|
+
);
|
|
282
|
+
return await client.sendTextMessage(roomId, out.text);
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
/** Whether the "no markdown mode here" warning has already been emitted. */
|
|
286
|
+
warnedAboutFormat = false;
|
|
287
|
+
/**
|
|
288
|
+
* Say, once, that a declared `markdown` has nowhere to go on this platform.
|
|
289
|
+
*
|
|
290
|
+
* Matrix's only markup type is HTML. A caller declaring `markdown` is asking for something
|
|
291
|
+
* the protocol does not have, and putting the markdown in the HTML field would corrupt it.
|
|
292
|
+
*
|
|
293
|
+
* @internal
|
|
294
|
+
*/
|
|
295
|
+
warnFormatUnsupported(format) {
|
|
296
|
+
if (format === void 0 || format === "plain" || format === "html") return;
|
|
297
|
+
if (this.warnedAboutFormat) return;
|
|
298
|
+
this.warnedAboutFormat = true;
|
|
299
|
+
process.stderr.write(
|
|
300
|
+
`[gateway-matrix] format="${format}" was declared, and Matrix has no markdown mode \u2014 its only markup type is HTML. Sending as plain text; this is logged once.
|
|
301
|
+
`
|
|
302
|
+
);
|
|
303
|
+
}
|
|
241
304
|
onInbound(handler) {
|
|
242
305
|
this.inboundHandler = handler;
|
|
243
306
|
return () => {
|
|
@@ -306,6 +369,15 @@ var MatrixAdapter = class extends BasePlatformAdapter {
|
|
|
306
369
|
`
|
|
307
370
|
);
|
|
308
371
|
}
|
|
372
|
+
/**
|
|
373
|
+
* Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
|
|
374
|
+
*
|
|
375
|
+
* One line over `runHandler`, which owns the containment: a handler is user code, its throw is
|
|
376
|
+
* named as the handler's failure rather than the platform's, and delivery continues.
|
|
377
|
+
*/
|
|
378
|
+
async deliver(event) {
|
|
379
|
+
return this.runHandler(this.inboundHandler, event);
|
|
380
|
+
}
|
|
309
381
|
};
|
|
310
382
|
function isAbortError(err) {
|
|
311
383
|
if (typeof err !== "object" || err === null) return false;
|
|
@@ -314,6 +386,11 @@ function isAbortError(err) {
|
|
|
314
386
|
if (e.code === 20) return true;
|
|
315
387
|
return typeof e.message === "string" && /aborted/i.test(e.message);
|
|
316
388
|
}
|
|
389
|
+
function isMalformedRequest(err) {
|
|
390
|
+
const e = err;
|
|
391
|
+
if (e.httpStatus !== 400) return false;
|
|
392
|
+
return e.errcode === "M_BAD_JSON" || e.errcode === "M_INVALID_PARAM";
|
|
393
|
+
}
|
|
317
394
|
function mapMatrixError(err) {
|
|
318
395
|
const e = err;
|
|
319
396
|
const status = e.httpStatus ?? 0;
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/errors.ts","../src/alias.ts","../src/client.ts","../src/room-state.ts","../src/normalize.ts","../src/sync.ts","../src/adapter.ts"],"names":[],"mappings":";;;AAoBO,IAAM,kBAAA,GAAN,cAAiC,yBAAA,CAA0B;AAAA,EAC9C,IAAA,GAAO,oBAAA;AAAA,EACzB,YAAY,IAAA,EAAiC;AAC3C,IAAA,KAAA,CAAM,kBAAkB,IAAI,CAAA;AAAA,EAC9B;AACF;AASO,IAAM,oBAAA,GAAN,cAAmC,kBAAA,CAAmB;AAAA,EAC3D,WAAA,GAAc;AACZ,IAAA,KAAA,CAAM;AAAA,MACJ,IAAA,EAAM,mBAAA;AAAA,MACN,OAAA,EACE,qFAAA;AAAA,MACF,MAAA,EAAQ;AAAA,KACT,CAAA;AAAA,EACH;AACF;AAQO,IAAM,kBAAA,GAAN,cAAiC,kBAAA,CAAmB;AAAA,EACzD,YAAY,MAAA,EAAgB;AAC1B,IAAA,KAAA,CAAM;AAAA,MACJ,IAAA,EAAM,4BAAA;AAAA,MACN,OAAA,EAAS,wBAAwB,MAAM,CAAA,gDAAA,CAAA;AAAA,MACvC,MAAA,EAAQ;AAAA,KACT,CAAA;AAAA,EACH;AACF;;;ACnCO,IAAM,aAAN,MAAiB;AAAA,EACL,KAAA,uBAAY,GAAA,EAAoB;AAAA;AAAA,EAGjD,MAAM,OAAA,CAAQ,MAAA,EAA6B,OAAA,EAAkC;AAC3E,IAAA,IAAI,OAAA,CAAQ,UAAA,CAAW,GAAG,CAAA,EAAG,OAAO,OAAA;AACpC,IAAA,IAAI,CAAC,OAAA,CAAQ,UAAA,CAAW,GAAG,CAAA,EAAG;AAC5B,MAAA,MAAM,IAAI,kBAAA,CAAmB;AAAA,QAC3B,IAAA,EAAM,kBAAA;AAAA,QACN,OAAA,EAAS,CAAA,uCAAA,EAA0C,IAAA,CAAK,SAAA,CAAU,OAAO,CAAC,CAAA,6CAAA;AAAA,OAC3E,CAAA;AAAA,IACH;AACA,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,OAAO,CAAA;AACrC,IAAA,IAAI,MAAA,KAAW,QAAW,OAAO,MAAA;AACjC,IAAA,MAAM,EAAE,OAAA,EAAQ,GAAI,MAAM,MAAA,CAAO,kBAAkB,OAAO,CAAA;AAC1D,IAAA,IAAA,CAAK,KAAA,CAAM,GAAA,CAAI,OAAA,EAAS,OAAO,CAAA;AAC/B,IAAA,OAAO,OAAA;AAAA,EACT;AAAA;AAAA,EAGA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,MAAM,KAAA,EAAM;AAAA,EACnB;AAAA,EAEA,IAAA,GAAe;AACb,IAAA,OAAO,KAAK,KAAA,CAAM,IAAA;AAAA,EACpB;AACF;;;ACrBA,eAAsB,aAAA,GAA0C;AAC9D,EAAA,IAAI;AACF,IAAA,MAAM,GAAA,GAAM,MAAM,OAAO,eAAe,CAAA;AACxC,IAAA,OAAO,GAAA;AAAA,EACT,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,oBAAA,EAAqB;AAAA,EACjC;AACF;;;AC5BO,SAAS,kBAAkB,IAAA,EAAkD;AAClF,EAAA,IAAI,IAAA,KAAS,QAAW,OAAO,OAAA;AAC/B,EAAA,OAAO,IAAA,CAAK,oBAAA,EAAqB,KAAM,CAAA,GAAI,IAAA,GAAO,OAAA;AACpD;;;ACDO,SAAS,yBAAA,CACd,OACA,IAAA,EACgC;AAChC,EAAA,MAAM,OAAA,GAAU,MAAM,KAAA,EAAM;AAC5B,EAAA,MAAM,MAAA,GAAS,MAAM,SAAA,EAAU;AAC/B,EAAA,IAAI,OAAA,KAAY,MAAA,IAAa,MAAA,KAAW,MAAA,EAAW,OAAO,MAAA;AAC1D,EAAA,MAAM,WAAA,GAAc,kBAAkB,IAAI,CAAA;AAC1C,EAAA,MAAM,OAAA,GAAU,MAAM,UAAA,EAAW;AACjC,EAAA,MAAM,IAAA,GAAO,QAAQ,IAAA,IAAQ,EAAA;AAC7B,EAAA,OAAO;AAAA,IACL,EAAA,EAAI,OAAA;AAAA,IACJ,QAAA,EAAU,QAAA;AAAA,IACV,MAAA,EAAQ,EAAE,EAAA,EAAI,MAAA,EAAO;AAAA,IACrB,OAAA,EAAS;AAAA,MACP,IAAI,IAAA,CAAK,MAAA;AAAA,MACT,IAAA,EAAM;AAAA,KACR;AAAA,IACA,IAAA,EAAM,IAAA;AAAA,IACN,UAAA,EAAY,MAAM,KAAA,EAAM;AAAA,IACxB,MAAA,EAAQ;AAAA,MACN,QAAQ,IAAA,CAAK,MAAA;AAAA,MACb,OAAA;AAAA,MACA,WAAA,EAAa,KAAK,oBAAA,EAAqB;AAAA,MACvC,GAAA,EAAK;AAAA;AACP,GACF;AACF;;;ACXO,SAAS,wBACd,KAAA,EACA,IAAA,EACA,GAAA,GAAM,IAAA,CAAK,KAAI,EACN;AACT,EAAA,IAAI,KAAA,CAAM,OAAA,EAAQ,KAAM,gBAAA,EAAkB,OAAO,KAAA;AACjD,EAAA,MAAM,MAAA,GAAS,MAAM,SAAA,EAAU;AAC/B,EAAA,IAAI,MAAA,KAAW,IAAA,CAAK,SAAA,EAAW,OAAO,KAAA;AACtC,EAAA,IAAI,MAAM,KAAA,EAAM,GAAI,GAAA,GAAM,IAAA,CAAK,mBAAmB,OAAO,KAAA;AACzD,EAAA,OAAO,IAAA;AACT;AAyBO,SAAS,mBAAA,CACd,MAAA,EACA,OAAA,EACA,IAAA,EACsB;AACtB,EAAA,MAAM,OAAA,GAAU,CAAC,KAAA,EAAwB,IAAA,KAA+B;AACtE,IAAA,IAAI,CAAC,uBAAA,CAAwB,KAAA,EAAO,IAAI,CAAA,EAAG;AAC3C,IAAA,OAAA,CAAQ,OAAO,IAAI,CAAA;AAAA,EACrB,CAAA;AACA,EAAA,MAAA,CAAO,EAAA,CAAG,iBAAiB,OAAO,CAAA;AAClC,EAAA,OAAO;AAAA,IACL,WAAA,GAAoB;AAClB,MAAA,MAAA,CAAO,GAAA,CAAI,iBAAiB,OAAO,CAAA;AAAA,IACrC;AAAA,GACF;AACF;;;ACxDA,IAAM,oBAAA,GAAuB,GAAA;AAC7B,IAAM,kBAAA,GAAqB,EAAA;AAEpB,IAAM,aAAA,GAAN,cAA4B,mBAAA,CAAoB;AAAA,EAC5C,QAAA,GAAW,QAAA;AAAA,EACH,IAAA;AAAA,EACT,MAAA;AAAA,EACA,YAAA;AAAA,EACA,cAAA;AAAA,EACS,UAAA,GAAa,IAAI,UAAA,EAAW;AAAA,EACrC,SAAA,GAAY,KAAA;AAAA,EACH,eAAA,uBAAsB,GAAA,EAAY;AAAA;AAAA,EAE3C,WAAA,GAAc,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAcd,iBAAA,GAA6C;AACnD,IAAA,MAAM,IAAA,GAAO,UAAA,CAAW,KAAA,CAAM,IAAA,CAAK,UAAU,CAAA;AAC7C,IAAA,OAAO,CAAC,OAAO,IAAA,KACb,IAAA,CAAK,OAAO,IAAI,CAAA,CAAE,KAAA,CAAM,CAAC,GAAA,KAAiB;AACxC,MAAA,IAAI,IAAA,CAAK,WAAA,IAAe,YAAA,CAAa,GAAG,CAAA,EAAG;AACzC,QAAA,OAAO,IAAI,QAAkB,MAAM;AAAA,QAEnC,CAAC,CAAA;AAAA,MACH;AACA,MAAA,MAAM,GAAA;AAAA,IACR,CAAC,CAAA;AAAA,EACL;AAAA,EAEA,YAAY,IAAA,EAA4B;AACtC,IAAA,KAAA,EAAM;AACN,IAAA,IAAI,IAAA,CAAK,aAAA,CAAc,MAAA,KAAW,CAAA,EAAG;AACnC,MAAA,MAAM,IAAI,kBAAA,CAAmB;AAAA,QAC3B,IAAA,EAAM,yBAAA;AAAA,QACN,OAAA,EAAS;AAAA,OACV,CAAA;AAAA,IACH;AACA,IAAA,IAAI,IAAA,CAAK,WAAA,CAAY,MAAA,KAAW,CAAA,EAAG;AACjC,MAAA,MAAM,IAAI,kBAAA,CAAmB;AAAA,QAC3B,IAAA,EAAM,uBAAA;AAAA,QACN,OAAA,EACE;AAAA,OACH,CAAA;AAAA,IACH;AACA,IAAA,IAAI,IAAA,CAAK,OAAO,MAAA,KAAW,CAAA,IAAK,CAAC,IAAA,CAAK,MAAA,CAAO,UAAA,CAAW,GAAG,CAAA,EAAG;AAC5D,MAAA,MAAM,IAAI,kBAAA,CAAmB;AAAA,QAC3B,IAAA,EAAM,kBAAA;AAAA,QACN,OAAA,EAAS;AAAA,OACV,CAAA;AAAA,IACH;AACA,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACd;AAAA,EAEA,MAAM,OAAA,GAA4B;AAChC,IAAA,IAAI,IAAA,CAAK,WAAW,OAAO,IAAA;AAC3B,IAAA,IAAA,CAAK,WAAA,GAAc,KAAA;AACnB,IAAA,IAAI;AACF,MAAA,MAAM,GAAA,GAAM;AAAA,QACV,OAAA,EAAS,KAAK,IAAA,CAAK,aAAA;AAAA,QACnB,WAAA,EAAa,KAAK,IAAA,CAAK,WAAA;AAAA,QACvB,MAAA,EAAQ,KAAK,IAAA,CAAK,MAAA;AAAA,QAClB,OAAA,EAAS,KAAK,iBAAA;AAAkB,OAClC;AACA,MAAA,MAAM,OAAA,GAAU,KAAK,IAAA,CAAK,eAAA;AAC1B,MAAA,IAAA,CAAK,MAAA,GACH,OAAA,KAAY,KAAA,CAAA,GAAA,CACP,MAAM,aAAA,IAAiB,YAAA,CAAa,GAAG,CAAA,GACvC,OAAA,CAAQ,GAAG,CAAA;AAOlB,MAAA,MAAM,IAAA,CAAK,OAAO,MAAA,EAAO;AACzB,MAAA,MAAM,KAAK,MAAA,CAAO,WAAA,CAAY,EAAE,gBAAA,EAAkB,oBAAoB,CAAA;AACtE,MAAA,IAAA,CAAK,UAAA,EAAW;AAChB,MAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AACjB,MAAA,OAAO,IAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,MAAM,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AAC3D,MAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,iCAAA,EAAoC,GAAG;AAAA,CAAI,CAAA;AAChE,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AAAA,EAEA,MAAM,UAAA,GAA4B;AAChC,IAAA,IAAI,CAAC,KAAK,SAAA,EAAW;AAWrB,IAAA,IAAA,CAAK,WAAA,GAAc,IAAA;AACnB,IAAA,IAAA,CAAK,cAAc,WAAA,EAAY;AAC/B,IAAA,IAAA,CAAK,YAAA,GAAe,MAAA;AACpB,IAAA,IAAA,CAAK,QAAQ,UAAA,EAAW;AACxB,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,SAAA,GAAY,KAAA;AACjB,IAAA,IAAA,CAAK,cAAA,GAAiB,MAAA;AACtB,IAAA,IAAA,CAAK,WAAW,KAAA,EAAM;AAAA,EACxB;AAAA,EAEA,MAAM,YAAY,GAAA,EAA2C;AAC3D,IAAA,IAAI,GAAA,CAAI,IAAA,CAAK,MAAA,KAAW,CAAA,EAAG;AACzB,MAAA,OAAO,EAAE,IAAI,KAAA,EAAO,KAAA,EAAO,EAAE,IAAA,EAAM,YAAA,EAAc,OAAA,EAAS,wBAAA,EAAyB,EAAE;AAAA,IACvF;AACA,IAAA,IAAI,IAAA,CAAK,WAAW,MAAA,EAAW;AAC7B,MAAA,OAAO;AAAA,QACL,EAAA,EAAI,KAAA;AAAA,QACJ,KAAA,EAAO,EAAE,IAAA,EAAM,eAAA,EAAiB,SAAS,oCAAA;AAAqC,OAChF;AAAA,IACF;AACA,IAAA,IAAI;AACF,MAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,UAAA,CAAW,QAAQ,IAAA,CAAK,MAAA,EAAQ,GAAA,CAAI,OAAA,CAAQ,EAAE,CAAA;AACxE,MAAA,IAAI,IAAA,CAAK,WAAA,CAAY,MAAM,CAAA,EAAG;AAC5B,QAAA,IAAA,CAAK,kBAAkB,MAAM,CAAA;AAC7B,QAAA,OAAO;AAAA,UACL,EAAA,EAAI,KAAA;AAAA,UACJ,KAAA,EAAO;AAAA,YACL,IAAA,EAAM,4BAAA;AAAA,YACN,OAAA,EAAS,eAAe,MAAM,CAAA,oCAAA;AAAA;AAChC,SACF;AAAA,MACF;AACA,MAAA,MAAM,MAAM,MAAM,IAAA,CAAK,OAAO,eAAA,CAAgB,MAAA,EAAQ,IAAI,IAAI,CAAA;AAC9D,MAAA,OAAO,EAAE,EAAA,EAAI,IAAA,EAAM,SAAA,EAAW,IAAI,QAAA,EAAS;AAAA,IAC7C,SAAS,GAAA,EAAK;AACZ,MAAA,OAAO,eAAe,GAAG,CAAA;AAAA,IAC3B;AAAA,EACF;AAAA,EAEA,UAAU,OAAA,EAAoE;AAE5E,IAAA,IAAA,CAAK,cAAA,GAAiB,OAAA;AACtB,IAAA,OAAO,MAAM;AACX,MAAA,IAAI,IAAA,CAAK,cAAA,KAAmB,OAAA,EAAS,IAAA,CAAK,cAAA,GAAiB,MAAA;AAAA,IAC7D,CAAA;AAAA,EACF;AAAA;AAAA,EAGA,SAAA,GAAyC;AACvC,IAAA,OAAO,IAAA,CAAK,MAAA;AAAA,EACd;AAAA;AAAA,EAGA,eAAe,MAAA,EAA+B;AAC5C,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AACd,IAAA,IAAA,CAAK,SAAA,GAAY,IAAA;AACjB,IAAA,IAAA,CAAK,UAAA,EAAW;AAAA,EAClB;AAAA,EAEQ,UAAA,GAAmB;AACzB,IAAA,IAAI,IAAA,CAAK,WAAW,MAAA,EAAW;AAC/B,IAAA,MAAM,SAAS,IAAA,CAAK,MAAA;AACpB,IAAA,MAAM,IAAA,GAAO;AAAA,MACX,SAAA,EAAW,KAAK,IAAA,CAAK,MAAA;AAAA,MACrB,iBAAA,EAAmB,IAAA,CAAK,IAAA,CAAK,iBAAA,IAAqB;AAAA,KACpD;AACA,IAAA,IAAA,CAAK,YAAA,GAAe,mBAAA;AAAA,MAClB,MAAA;AAAA,MACA,CAAC,IAAqB,IAAA,KAAyB;AAC7C,QAAA,KAAK,KAAK,qBAAA,CAAsB,EAAA,EAAI,IAAI,CAAA,CAAE,KAAA,CAAM,CAAC,GAAA,KAAiB;AAChE,UAAA,MAAM,IAAI,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AACzD,UAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,+CAAA,EAAkD,CAAC;AAAA,CAAI,CAAA;AAAA,QAC9E,CAAC,CAAA;AAAA,MACH,CAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AAAA,EAEA,MAAc,qBAAA,CAAsB,KAAA,EAAwB,IAAA,EAAqC;AAC/F,IAAA,IAAI,IAAA,CAAK,WAAA,CAAY,IAAA,CAAK,MAAM,CAAA,EAAG;AACjC,MAAA,IAAA,CAAK,iBAAA,CAAkB,KAAK,MAAM,CAAA;AAClC,MAAA;AAAA,IACF;AACA,IAAA,MAAM,UAAA,GAAa,yBAAA,CAA0B,KAAA,EAAO,IAAI,CAAA;AACxD,IAAA,IAAI,eAAe,MAAA,EAAW;AAC9B,IAAA,IAAI,IAAA,CAAK,mBAAmB,MAAA,EAAW;AACvC,IAAA,IAAI;AACF,MAAA,MAAM,IAAA,CAAK,eAAe,UAAU,CAAA;AAAA,IACtC,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAI,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AACzD,MAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,gCAAA,EAAmC,CAAC;AAAA,CAAI,CAAA;AAAA,IAC/D;AAAA,EACF;AAAA,EAEQ,YAAY,MAAA,EAAyB;AAC3C,IAAA,IAAI,IAAA,CAAK,MAAA,KAAW,MAAA,EAAW,OAAO,KAAA;AACtC,IAAA,IAAI,IAAA,CAAK,MAAA,CAAO,eAAA,KAAoB,MAAA,EAAW,OAAO,KAAA;AACtD,IAAA,IAAI;AACF,MAAA,OAAO,IAAA,CAAK,MAAA,CAAO,eAAA,CAAgB,MAAM,CAAA;AAAA,IAC3C,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,KAAA;AAAA,IACT;AAAA,EACF;AAAA,EAEQ,kBAAkB,MAAA,EAAsB;AAC9C,IAAA,IAAI,IAAA,CAAK,eAAA,CAAgB,GAAA,CAAI,MAAM,CAAA,EAAG;AACtC,IAAA,IAAA,CAAK,eAAA,CAAgB,IAAI,MAAM,CAAA;AAC/B,IAAA,OAAA,CAAQ,MAAA,CAAO,KAAA;AAAA,MACb,yBAAyB,MAAM,CAAA;AAAA;AAAA,KACjC;AAAA,EACF;AACF;AAMA,SAAS,aAAa,GAAA,EAAuB;AAC3C,EAAA,IAAI,OAAO,GAAA,KAAQ,QAAA,IAAY,GAAA,KAAQ,MAAM,OAAO,KAAA;AACpD,EAAA,MAAM,CAAA,GAAI,GAAA;AACV,EAAA,IAAI,CAAA,CAAE,IAAA,KAAS,YAAA,EAAc,OAAO,IAAA;AACpC,EAAA,IAAI,CAAA,CAAE,IAAA,KAAS,EAAA,EAAI,OAAO,IAAA;AAC1B,EAAA,OAAO,OAAO,CAAA,CAAE,OAAA,KAAY,YAAY,UAAA,CAAW,IAAA,CAAK,EAAE,OAAO,CAAA;AACnE;AAUA,SAAS,eAAe,GAAA,EAA0B;AAChD,EAAA,MAAM,CAAA,GAAI,GAAA;AACV,EAAA,MAAM,MAAA,GAAS,EAAE,UAAA,IAAc,CAAA;AAC/B,EAAA,IAAI,MAAA,KAAW,GAAA,IAAO,CAAA,CAAE,OAAA,KAAY,kBAAA,EAAoB;AACtD,IAAA,OAAO,EAAE,EAAA,EAAI,KAAA,EAAO,KAAA,EAAO,EAAE,IAAA,EAAM,YAAA,EAAc,OAAA,EAAS,CAAA,CAAE,OAAA,IAAW,mBAAA,EAAoB,EAAE;AAAA,EAC/F;AACA,EAAA,IAAI,WAAW,GAAA,IAAO,MAAA,KAAW,GAAA,IAAO,CAAA,CAAE,YAAY,aAAA,EAAe;AACnE,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,OAAO,EAAE,IAAA,EAAM,qBAAqB,OAAA,EAAS,CAAA,CAAE,WAAW,yBAAA;AAA0B,KACtF;AAAA,EACF;AACA,EAAA,IAAI,MAAA,KAAW,GAAA,IAAO,CAAA,CAAE,OAAA,KAAY,aAAA,EAAe;AACjD,IAAA,OAAO;AAAA,MACL,EAAA,EAAI,KAAA;AAAA,MACJ,OAAO,EAAE,IAAA,EAAM,aAAa,OAAA,EAAS,CAAA,CAAE,WAAW,2BAAA;AAA4B,KAChF;AAAA,EACF;AACA,EAAA,OAAO;AAAA,IACL,EAAA,EAAI,KAAA;AAAA,IACJ,KAAA,EAAO;AAAA,MACL,IAAA,EAAM,aAAA;AAAA,MACN,OAAA,EAAS,EAAE,OAAA,KAAY,GAAA,YAAe,QAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AAAA;AACxE,GACF;AACF","file":"index.js","sourcesContent":["/**\n * Typed errors for `@theokit/gateway-matrix`.\n *\n * `ConfigurationError` extends the shared core `GatewayConfigurationError`\n * base (roadmap M2). Behavior byte-identical (pinned by `tests/errors.test.ts`).\n */\n\nimport { GatewayConfigurationError, type GatewayConfigurationErrorOptions } from \"@theokit/gateway\";\n\n/** @knipignore — public input shape for `ConfigurationError` constructor (caller-extensible). */\nexport type ConfigurationErrorOptions = GatewayConfigurationErrorOptions;\n\n/**\n * Misconfiguration of this adapter, raised before any network call.\n *\n * Extends the shared core base so every gateway package reports configuration faults in one shape:\n * a structured `code` the caller can branch on, tagged with `\"gateway-matrix\"` as the origin. A\n * missing credential or an unsupported option is a programmer error, not a transient failure —\n * these are never retried.\n */\nexport class ConfigurationError extends GatewayConfigurationError {\n override readonly name = \"ConfigurationError\";\n constructor(opts: ConfigurationErrorOptions) {\n super(\"gateway-matrix\", opts);\n }\n}\n\n/**\n * The platform SDK this adapter needs is declared as a peer dependency and is not installed.\n *\n * Raised at connect time rather than at import, so a project that installs several gateway packages\n * only pays for the SDKs of the ones it actually starts. The message names the exact package and\n * the command that installs it.\n */\nexport class SDKNotInstalledError extends ConfigurationError {\n constructor() {\n super({\n code: \"sdk_not_installed\",\n message:\n 'gateway-matrix: peer-dep \"matrix-js-sdk\" not installed. Run: pnpm add matrix-js-sdk',\n detail: \"matrix-js-sdk\",\n });\n }\n}\n\n/**\n * The room is end-to-end encrypted, which this adapter cannot read.\n *\n * E2EE is deferred to v0.2. Raised rather than silently ignoring the room, because a bot that\n * appears connected and never sees a message is far harder to diagnose than one that says why.\n */\nexport class EncryptedRoomError extends ConfigurationError {\n constructor(roomId: string) {\n super({\n code: \"encrypted_room_unsupported\",\n message: `gateway-matrix: room ${roomId} is end-to-end encrypted (E2EE deferred to v0.2)`,\n detail: roomId,\n });\n }\n}\n","/**\n * Matrix alias resolution + caching (D419).\n *\n * Accepts:\n * - Room id (`!abc123:server`) — pass-through.\n * - Alias (`#general:server`) — resolved via `client.getRoomIdForAlias`.\n *\n * Other shapes throw `ConfigurationError({ code: \"invalid_room_ref\" })`.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\n\n/** @knipignore — minimal Client interface `AliasCache.resolve` accepts; useful for callers building their own resolver. */\nexport interface AliasResolverClient {\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n}\n\n/**\n * Resolves a Matrix room alias (`#room:server`) to its room id, remembering the answer.\n *\n * An alias resolves through a server round-trip, and the mapping effectively never changes, so\n * repeating it once per outbound message is pure latency. A value that is already a room id is\n * returned untouched, which lets callers pass either form.\n */\nexport class AliasCache {\n private readonly cache = new Map<string, string>();\n\n /** Returns the room id; resolves aliases via the client + caches. */\n async resolve(client: AliasResolverClient, refOrId: string): Promise<string> {\n if (refOrId.startsWith(\"!\")) return refOrId;\n if (!refOrId.startsWith(\"#\")) {\n throw new ConfigurationError({\n code: \"invalid_room_ref\",\n message: `gateway-matrix: invalid room reference ${JSON.stringify(refOrId)} — expected '!' (room id) or '#' (alias)`,\n });\n }\n const cached = this.cache.get(refOrId);\n if (cached !== undefined) return cached;\n const { room_id } = await client.getRoomIdForAlias(refOrId);\n this.cache.set(refOrId, room_id);\n return room_id;\n }\n\n /** Drop all cached resolutions. Useful for tests + admin-rename recovery. */\n clear(): void {\n this.cache.clear();\n }\n\n size(): number {\n return this.cache.size;\n }\n}\n","/**\n * Lazy `matrix-js-sdk` loader.\n */\n\nimport { SDKNotInstalledError } from \"./errors.js\";\nimport type { MatrixClientLike } from \"./sync.js\";\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport interface MatrixSdkClient extends MatrixClientLike {\n startClient(opts: { initialSyncLimit: number }): Promise<void>;\n stopClient(): void;\n sendTextMessage(roomId: string, text: string): Promise<{ event_id: string }>;\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n getRoom(roomId: string): MatrixRoomLike | null;\n isRoomEncrypted?(roomId: string): boolean;\n /** Best-effort current user id; matrix-js-sdk returns `string | null`. */\n getUserId(): string | null;\n /**\n * `/_matrix/client/v3/account/whoami` — the cheapest call that makes the\n * server judge the access token. `startClient` does not: it begins syncing\n * asynchronously and resolves regardless, so without this an invalid token\n * produces a connected-looking adapter that never receives anything.\n */\n whoami(): Promise<{ user_id: string }>;\n}\n\ninterface MatrixSdkModule {\n createClient(opts: { baseUrl: string; accessToken: string; userId: string }): MatrixSdkClient;\n}\n\nexport async function loadMatrixSdk(): Promise<MatrixSdkModule> {\n try {\n const mod = await import(\"matrix-js-sdk\");\n return mod as unknown as MatrixSdkModule;\n } catch {\n throw new SDKNotInstalledError();\n }\n}\n","/**\n * Room state helpers (D416).\n *\n * Matrix has no native \"DM\" concept — DMs are rooms with 2 members.\n * The canonical heuristic: `member_count === 2 → \"dm\"`, else `\"group\"`.\n */\n\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport function detectChannelType(room: MatrixRoomLike | undefined): \"dm\" | \"group\" {\n if (room === undefined) return \"group\";\n return room.getJoinedMemberCount() === 2 ? \"dm\" : \"group\";\n}\n","/**\n * Inbound normalization: MatrixEvent + Room → MatrixMessageEvent.\n *\n * @public\n */\n\nimport type { MatrixMessageEvent } from \"@theokit/gateway\";\n\nimport { detectChannelType } from \"./room-state.js\";\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport function matrixEventToMessageEvent(\n event: MatrixEventLike,\n room: MatrixRoomLike,\n): MatrixMessageEvent | undefined {\n const eventId = event.getId();\n const sender = event.getSender();\n if (eventId === undefined || sender === undefined) return undefined;\n const channelType = detectChannelType(room);\n const content = event.getContent();\n const body = content.body ?? \"\";\n return {\n id: eventId,\n platform: \"matrix\",\n sender: { id: sender },\n channel: {\n id: room.roomId,\n type: channelType,\n },\n text: body,\n receivedAt: event.getTs(),\n matrix: {\n roomId: room.roomId,\n eventId,\n memberCount: room.getJoinedMemberCount(),\n raw: event,\n },\n };\n}\n","/**\n * Sync timeline filter (D415, EC-3 absorbed).\n *\n * Wraps `client.on(\"Room.timeline\", listener)` with 3 filters:\n *\n * 1. Drop non-`m.room.message` events (D413).\n * 2. Drop bot's own messages (loop guard, D275 mirror).\n * 3. **EC-3**: drop events older than `freshnessWindowMs` (default 60s)\n * — initial sync from `matrix-js-sdk` delivers ~10 historical events\n * per joined room, which would otherwise trigger an LLM-call storm.\n */\n\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport interface SyncFilterOpts {\n readonly botUserId: string;\n readonly freshnessWindowMs: number;\n}\n\n/**\n * Decide whether a timeline event should reach the handler.\n *\n * Matrix replays room history on sync, so a freshly started bot would otherwise answer every message\n * it can still see — which is a reply storm in a busy room and an infinite loop in a quiet one. This\n * drops the bot's own events and anything older than the freshness window. `now` is injectable so\n * the decision is testable without waiting.\n */\nexport function shouldDispatchSyncEvent(\n event: MatrixEventLike,\n opts: SyncFilterOpts,\n now = Date.now(),\n): boolean {\n if (event.getType() !== \"m.room.message\") return false;\n const sender = event.getSender();\n if (sender === opts.botUserId) return false;\n if (event.getTs() < now - opts.freshnessWindowMs) return false;\n return true;\n}\n\n/** A live timeline listener, with the handle that detaches it again. */\nexport interface TimelineSubscription {\n unsubscribe(): void;\n}\n\n/**\n * The slice of `matrix-js-sdk`'s client this adapter actually uses.\n *\n * Narrow on purpose: it is what lets the sync logic be tested against a few lines of fake rather\n * than a running homeserver, and it states the real coupling to the SDK — two event methods.\n */\nexport interface MatrixClientLike {\n on(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n off(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n}\n\n/**\n * Attach `handler` to the client's room timeline, filtered by {@link shouldDispatchSyncEvent}.\n *\n * Returns the subscription rather than leaving the listener attached forever: an adapter that\n * reconnects without detaching accumulates listeners, and every inbound message is then handled\n * once per reconnect.\n */\nexport function subscribeToTimeline(\n client: MatrixClientLike,\n handler: (event: MatrixEventLike, room: MatrixRoomLike) => void,\n opts: SyncFilterOpts,\n): TimelineSubscription {\n const wrapped = (event: MatrixEventLike, room: MatrixRoomLike): void => {\n if (!shouldDispatchSyncEvent(event, opts)) return;\n handler(event, room);\n };\n client.on(\"Room.timeline\", wrapped);\n return {\n unsubscribe(): void {\n client.off(\"Room.timeline\", wrapped);\n },\n };\n}\n","/**\n * `MatrixAdapter` — implements BasePlatformAdapter over matrix-js-sdk.\n * ADRs D413-D421.\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 { AliasCache } from \"./alias.js\";\nimport { loadMatrixSdk, type MatrixSdkClient } from \"./client.js\";\nimport { ConfigurationError } from \"./errors.js\";\nimport { matrixEventToMessageEvent } from \"./normalize.js\";\nimport { subscribeToTimeline, type TimelineSubscription } from \"./sync.js\";\nimport type { MatrixAdapterOptions, MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nconst DEFAULT_FRESHNESS_MS = 60_000;\nconst INITIAL_SYNC_LIMIT = 10;\n\nexport class MatrixAdapter extends BasePlatformAdapter {\n readonly platform = \"matrix\" as const;\n private readonly opts: MatrixAdapterOptions;\n private client: MatrixSdkClient | undefined;\n private subscription: TimelineSubscription | undefined;\n private inboundHandler: ((event: GatewayMessageEvent) => Promise<void>) | undefined;\n private readonly aliasCache = new AliasCache();\n private connected = false;\n private readonly warnedEncrypted = new Set<string>();\n /** True only between disconnect() and the next connect() — see #12. */\n private tearingDown = false;\n\n /**\n * `fetch` for the SDK that leaves teardown aborts unsettled instead of\n * rejecting (#12).\n *\n * A request aborted while we are tearing the client down has no consumer left\n * that could act on the outcome, so an unsettled promise costs a continuation\n * and nothing else; the alternative is a rejection with no handler anywhere,\n * which ends the host process. It is scoped to the teardown window on purpose:\n * a consumer using the `getClient()` escape hatch (D421) may pass its own\n * abort signal to `search()` or `slidingSync()` and MUST still see those\n * rejections, so outside teardown every error propagates untouched.\n */\n private teardownSafeFetch(): typeof globalThis.fetch {\n const base = globalThis.fetch.bind(globalThis);\n return (input, init) =>\n base(input, init).catch((err: unknown) => {\n if (this.tearingDown && isAbortError(err)) {\n return new Promise<Response>(() => {\n /* deliberately never settles — see the doc comment */\n });\n }\n throw err;\n });\n }\n\n constructor(opts: MatrixAdapterOptions) {\n super();\n if (opts.homeserverUrl.length === 0) {\n throw new ConfigurationError({\n code: \"homeserver_url_required\",\n message: 'gateway-matrix: opts.homeserverUrl is empty (e.g. \"https://matrix.org\")',\n });\n }\n if (opts.accessToken.length === 0) {\n throw new ConfigurationError({\n code: \"access_token_required\",\n message:\n \"gateway-matrix: opts.accessToken is empty (Element → Settings → Help & About → Advanced → Access Token)\",\n });\n }\n if (opts.userId.length === 0 || !opts.userId.startsWith(\"@\")) {\n throw new ConfigurationError({\n code: \"user_id_required\",\n message: 'gateway-matrix: opts.userId must be a Matrix user id (e.g. \"@bot:matrix.org\")',\n });\n }\n this.opts = opts;\n }\n\n async connect(): Promise<boolean> {\n if (this.connected) return true;\n this.tearingDown = false;\n try {\n const cfg = {\n baseUrl: this.opts.homeserverUrl,\n accessToken: this.opts.accessToken,\n userId: this.opts.userId,\n fetchFn: this.teardownSafeFetch(),\n };\n const factory = this.opts.__clientFactory;\n this.client =\n factory === undefined\n ? (await loadMatrixSdk()).createClient(cfg)\n : (factory(cfg) as MatrixSdkClient);\n // Validate the credential BEFORE reporting success. `startClient` kicks\n // off the sync loop asynchronously and resolves whether or not the token\n // is any good — so connect() used to answer `true` for a token the server\n // rejects, leaving an operator with a healthy-looking adapter and total\n // silence. Every sibling adapter returns false here; this one did not,\n // and only a real homeserver could show it.\n await this.client.whoami();\n await this.client.startClient({ initialSyncLimit: INITIAL_SYNC_LIMIT });\n this.attachSync();\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-matrix] connect failed: ${msg}\\n`);\n return false;\n }\n }\n\n async disconnect(): Promise<void> {\n if (!this.connected) return;\n // Issue #12. `stopClient()` aborts the requests still in flight, and the\n // AbortError escapes as an UNHANDLED rejection — the rejecting promise is\n // the SDK's own `authedRequest` wrapper, which no caller catches and which\n // we cannot reach. Node has terminated on unhandled rejections by default\n // since v15, so an application calling disconnect() inside a reconnect loop\n // could be killed by its own clean shutdown. Measured against a real\n // homeserver: 7 occurrences in 8 connect/disconnect cycles.\n //\n // `teardownSafeFetch` closes it at the only seam the SDK offers. The flag is\n // set here, before the abort, and cleared by the next connect().\n this.tearingDown = true;\n this.subscription?.unsubscribe();\n this.subscription = undefined;\n this.client?.stopClient();\n this.client = undefined;\n this.connected = false;\n this.inboundHandler = undefined;\n this.aliasCache.clear();\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.client === undefined) {\n return {\n ok: false,\n error: { code: \"not_connected\", message: \"MatrixAdapter.connect() not called\" },\n };\n }\n try {\n const roomId = await this.aliasCache.resolve(this.client, out.channel.id);\n if (this.isEncrypted(roomId)) {\n this.warnEncryptedOnce(roomId);\n return {\n ok: false,\n error: {\n code: \"encrypted_room_unsupported\",\n message: `Matrix room ${roomId} is encrypted; E2EE deferred to v0.2`,\n },\n };\n }\n const res = await this.client.sendTextMessage(roomId, out.text);\n return { ok: true, messageId: res.event_id };\n } catch (err) {\n return mapMatrixError(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 (D421) — caller can drive matrix-js-sdk directly for advanced features. */\n getClient(): MatrixSdkClient | undefined {\n return this.client;\n }\n\n /** Used by tests to install a mock SDK client + flip connected flag. */\n _installClient(client: MatrixSdkClient): void {\n this.client = client;\n this.connected = true;\n this.attachSync();\n }\n\n private attachSync(): void {\n if (this.client === undefined) return;\n const client = this.client;\n const opts = {\n botUserId: this.opts.userId,\n freshnessWindowMs: this.opts.freshnessWindowMs ?? DEFAULT_FRESHNESS_MS,\n };\n this.subscription = subscribeToTimeline(\n client,\n (ev: MatrixEventLike, room: MatrixRoomLike) => {\n void this.dispatchTimelineEvent(ev, room).catch((err: unknown) => {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] dispatchTimelineEvent failed: ${m}\\n`);\n });\n },\n opts,\n );\n }\n\n private async dispatchTimelineEvent(event: MatrixEventLike, room: MatrixRoomLike): Promise<void> {\n if (this.isEncrypted(room.roomId)) {\n this.warnEncryptedOnce(room.roomId);\n return;\n }\n const normalized = matrixEventToMessageEvent(event, room);\n if (normalized === undefined) return;\n if (this.inboundHandler === undefined) return;\n try {\n await this.inboundHandler(normalized);\n } catch (err) {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] handler threw: ${m}\\n`);\n }\n }\n\n private isEncrypted(roomId: string): boolean {\n if (this.client === undefined) return false;\n if (this.client.isRoomEncrypted === undefined) return false;\n try {\n return this.client.isRoomEncrypted(roomId);\n } catch {\n return false;\n }\n }\n\n private warnEncryptedOnce(roomId: string): void {\n if (this.warnedEncrypted.has(roomId)) return;\n this.warnedEncrypted.add(roomId);\n process.stderr.write(\n `[gateway-matrix] room ${roomId} is end-to-end encrypted; skipping (E2EE deferred to v0.2)\\n`,\n );\n }\n}\n\n/**\n * Narrow abort detection. `DOMException.ABORT_ERR` is 20; the message check\n * covers runtimes that report the abort without the standard name or code.\n */\nfunction isAbortError(err: unknown): boolean {\n if (typeof err !== \"object\" || err === null) return false;\n const e = err as { name?: unknown; code?: unknown; message?: unknown };\n if (e.name === \"AbortError\") return true;\n if (e.code === 20) return true;\n return typeof e.message === \"string\" && /aborted/i.test(e.message);\n}\n\ninterface MatrixRestError {\n httpStatus?: number;\n errcode?: string;\n message?: string;\n name?: string;\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: error mapping ladder is exhaustive — each branch maps one Matrix errcode/HTTP status to one canonical code; splitting hurts traceability.\nfunction mapMatrixError(err: unknown): SendResult {\n const e = err as MatrixRestError;\n const status = e.httpStatus ?? 0;\n if (status === 429 || e.errcode === \"M_LIMIT_EXCEEDED\") {\n return { ok: false, error: { code: \"rate_limit\", message: e.message ?? \"Matrix rate limit\" } };\n }\n if (status === 401 || status === 403 || e.errcode === \"M_FORBIDDEN\") {\n return {\n ok: false,\n error: { code: \"permission_denied\", message: e.message ?? \"Matrix permission error\" },\n };\n }\n if (status === 404 || e.errcode === \"M_NOT_FOUND\") {\n return {\n ok: false,\n error: { code: \"not_found\", message: e.message ?? \"Matrix resource not found\" },\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"]}
|
|
1
|
+
{"version":3,"sources":["../src/errors.ts","../src/alias.ts","../src/client.ts","../src/room-state.ts","../src/normalize.ts","../src/sync.ts","../src/adapter.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Typed errors for `@theokit/gateway-matrix`.\n *\n * `ConfigurationError` extends the shared core `GatewayConfigurationError`\n * base (roadmap M2). Behavior byte-identical (pinned by `tests/errors.test.ts`).\n */\n\nimport { GatewayConfigurationError, type GatewayConfigurationErrorOptions } from \"@theokit/gateway\";\n\n/** @knipignore — public input shape for `ConfigurationError` constructor (caller-extensible). */\nexport type ConfigurationErrorOptions = GatewayConfigurationErrorOptions;\n\n/**\n * Misconfiguration of this adapter, raised before any network call.\n *\n * Extends the shared core base so every gateway package reports configuration faults in one shape:\n * a structured `code` the caller can branch on, tagged with `\"gateway-matrix\"` as the origin. A\n * missing credential or an unsupported option is a programmer error, not a transient failure —\n * these are never retried.\n */\nexport class ConfigurationError extends GatewayConfigurationError {\n override readonly name = \"ConfigurationError\";\n constructor(opts: ConfigurationErrorOptions) {\n super(\"gateway-matrix\", opts);\n }\n}\n\n/**\n * The platform SDK this adapter needs is declared as a peer dependency and is not installed.\n *\n * Raised at connect time rather than at import, so a project that installs several gateway packages\n * only pays for the SDKs of the ones it actually starts. The message names the exact package and\n * the command that installs it.\n */\nexport class SDKNotInstalledError extends ConfigurationError {\n constructor() {\n super({\n code: \"sdk_not_installed\",\n message:\n 'gateway-matrix: peer-dep \"matrix-js-sdk\" not installed. Run: pnpm add matrix-js-sdk',\n detail: \"matrix-js-sdk\",\n });\n }\n}\n\n/**\n * The room is end-to-end encrypted, which this adapter cannot read.\n *\n * E2EE is deferred to v0.2. Raised rather than silently ignoring the room, because a bot that\n * appears connected and never sees a message is far harder to diagnose than one that says why.\n */\nexport class EncryptedRoomError extends ConfigurationError {\n constructor(roomId: string) {\n super({\n code: \"encrypted_room_unsupported\",\n message: `gateway-matrix: room ${roomId} is end-to-end encrypted (E2EE deferred to v0.2)`,\n detail: roomId,\n });\n }\n}\n","/**\n * Matrix alias resolution + caching (D419).\n *\n * Accepts:\n * - Room id (`!abc123:server`) — pass-through.\n * - Alias (`#general:server`) — resolved via `client.getRoomIdForAlias`.\n *\n * Other shapes throw `ConfigurationError({ code: \"invalid_room_ref\" })`.\n */\n\nimport { ConfigurationError } from \"./errors.js\";\n\n/** @knipignore — minimal Client interface `AliasCache.resolve` accepts; useful for callers building their own resolver. */\nexport interface AliasResolverClient {\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n}\n\n/**\n * Resolves a Matrix room alias (`#room:server`) to its room id, remembering the answer.\n *\n * An alias resolves through a server round-trip, and the mapping effectively never changes, so\n * repeating it once per outbound message is pure latency. A value that is already a room id is\n * returned untouched, which lets callers pass either form.\n */\nexport class AliasCache {\n private readonly cache = new Map<string, string>();\n\n /** Returns the room id; resolves aliases via the client + caches. */\n async resolve(client: AliasResolverClient, refOrId: string): Promise<string> {\n if (refOrId.startsWith(\"!\")) return refOrId;\n if (!refOrId.startsWith(\"#\")) {\n throw new ConfigurationError({\n code: \"invalid_room_ref\",\n message: `gateway-matrix: invalid room reference ${JSON.stringify(refOrId)} — expected '!' (room id) or '#' (alias)`,\n });\n }\n const cached = this.cache.get(refOrId);\n if (cached !== undefined) return cached;\n const { room_id } = await client.getRoomIdForAlias(refOrId);\n this.cache.set(refOrId, room_id);\n return room_id;\n }\n\n /** Drop all cached resolutions. Useful for tests + admin-rename recovery. */\n clear(): void {\n this.cache.clear();\n }\n\n size(): number {\n return this.cache.size;\n }\n}\n","/**\n * Lazy `matrix-js-sdk` loader.\n */\n\nimport { SDKNotInstalledError } from \"./errors.js\";\nimport type { MatrixClientLike } from \"./sync.js\";\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport interface MatrixSdkClient extends MatrixClientLike {\n startClient(opts: { initialSyncLimit: number }): Promise<void>;\n stopClient(): void;\n sendTextMessage(roomId: string, text: string): Promise<{ event_id: string }>;\n /**\n * Send a message whose content object the caller composes.\n *\n * `sendTextMessage` is a convenience that hard-codes `msgtype: m.text` and a bare `body`, so\n * it has nowhere to put `formatted_body` — the field Matrix documents for markup. Honouring\n * `OutboundMessage.format` therefore needs the general call, not a new argument on the\n * convenience one.\n */\n sendMessage?(roomId: string, content: Record<string, unknown>): Promise<{ event_id: string }>;\n getRoomIdForAlias(alias: string): Promise<{ room_id: string }>;\n getRoom(roomId: string): MatrixRoomLike | null;\n isRoomEncrypted?(roomId: string): boolean;\n /** Best-effort current user id; matrix-js-sdk returns `string | null`. */\n getUserId(): string | null;\n /**\n * `/_matrix/client/v3/account/whoami` — the cheapest call that makes the\n * server judge the access token. `startClient` does not: it begins syncing\n * asynchronously and resolves regardless, so without this an invalid token\n * produces a connected-looking adapter that never receives anything.\n */\n whoami(): Promise<{ user_id: string }>;\n}\n\ninterface MatrixSdkModule {\n createClient(opts: { baseUrl: string; accessToken: string; userId: string }): MatrixSdkClient;\n}\n\nexport async function loadMatrixSdk(): Promise<MatrixSdkModule> {\n try {\n const mod = await import(\"matrix-js-sdk\");\n return mod as unknown as MatrixSdkModule;\n } catch {\n throw new SDKNotInstalledError();\n }\n}\n","/**\n * Room state helpers (D416).\n *\n * Matrix has no native \"DM\" concept — DMs are rooms with 2 members.\n * The canonical heuristic: `member_count === 2 → \"dm\"`, else `\"group\"`.\n */\n\nimport type { MatrixRoomLike } from \"./types.js\";\n\nexport function detectChannelType(room: MatrixRoomLike | undefined): \"dm\" | \"group\" {\n if (room === undefined) return \"group\";\n return room.getJoinedMemberCount() === 2 ? \"dm\" : \"group\";\n}\n","/**\n * Inbound normalization: MatrixEvent + Room → MatrixMessageEvent.\n *\n * @public\n */\n\nimport type { MatrixMessageEvent } from \"@theokit/gateway\";\n\nimport { detectChannelType } from \"./room-state.js\";\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport function matrixEventToMessageEvent(\n event: MatrixEventLike,\n room: MatrixRoomLike,\n): MatrixMessageEvent | undefined {\n const eventId = event.getId();\n const sender = event.getSender();\n if (eventId === undefined || sender === undefined) return undefined;\n const channelType = detectChannelType(room);\n const content = event.getContent();\n const body = content.body ?? \"\";\n return {\n id: eventId,\n platform: \"matrix\",\n sender: { id: sender },\n channel: {\n id: room.roomId,\n type: channelType,\n },\n text: body,\n receivedAt: event.getTs(),\n matrix: {\n roomId: room.roomId,\n eventId,\n memberCount: room.getJoinedMemberCount(),\n raw: event,\n },\n };\n}\n","/**\n * Sync timeline filter (D415, EC-3 absorbed).\n *\n * Wraps `client.on(\"Room.timeline\", listener)` with 3 filters:\n *\n * 1. Drop non-`m.room.message` events (D413).\n * 2. Drop bot's own messages (loop guard, D275 mirror).\n * 3. **EC-3**: drop events older than `freshnessWindowMs` (default 60s)\n * — initial sync from `matrix-js-sdk` delivers ~10 historical events\n * per joined room, which would otherwise trigger an LLM-call storm.\n */\n\nimport type { MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nexport interface SyncFilterOpts {\n readonly botUserId: string;\n readonly freshnessWindowMs: number;\n}\n\n/**\n * Decide whether a timeline event should reach the handler.\n *\n * Matrix replays room history on sync, so a freshly started bot would otherwise answer every message\n * it can still see — which is a reply storm in a busy room and an infinite loop in a quiet one. This\n * drops the bot's own events and anything older than the freshness window. `now` is injectable so\n * the decision is testable without waiting.\n */\nexport function shouldDispatchSyncEvent(\n event: MatrixEventLike,\n opts: SyncFilterOpts,\n now = Date.now(),\n): boolean {\n if (event.getType() !== \"m.room.message\") return false;\n const sender = event.getSender();\n if (sender === opts.botUserId) return false;\n if (event.getTs() < now - opts.freshnessWindowMs) return false;\n return true;\n}\n\n/** A live timeline listener, with the handle that detaches it again. */\nexport interface TimelineSubscription {\n unsubscribe(): void;\n}\n\n/**\n * The slice of `matrix-js-sdk`'s client this adapter actually uses.\n *\n * Narrow on purpose: it is what lets the sync logic be tested against a few lines of fake rather\n * than a running homeserver, and it states the real coupling to the SDK — two event methods.\n */\nexport interface MatrixClientLike {\n on(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n off(event: \"Room.timeline\", listener: (e: MatrixEventLike, r: MatrixRoomLike) => void): void;\n}\n\n/**\n * Attach `handler` to the client's room timeline, filtered by {@link shouldDispatchSyncEvent}.\n *\n * Returns the subscription rather than leaving the listener attached forever: an adapter that\n * reconnects without detaching accumulates listeners, and every inbound message is then handled\n * once per reconnect.\n */\nexport function subscribeToTimeline(\n client: MatrixClientLike,\n handler: (event: MatrixEventLike, room: MatrixRoomLike) => void,\n opts: SyncFilterOpts,\n): TimelineSubscription {\n const wrapped = (event: MatrixEventLike, room: MatrixRoomLike): void => {\n if (!shouldDispatchSyncEvent(event, opts)) return;\n handler(event, room);\n };\n client.on(\"Room.timeline\", wrapped);\n return {\n unsubscribe(): void {\n client.off(\"Room.timeline\", wrapped);\n },\n };\n}\n","/**\n * `MatrixAdapter` — implements BasePlatformAdapter over matrix-js-sdk.\n * ADRs D413-D421.\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 { AliasCache } from \"./alias.js\";\nimport { loadMatrixSdk, type MatrixSdkClient } from \"./client.js\";\nimport { ConfigurationError } from \"./errors.js\";\nimport { matrixEventToMessageEvent } from \"./normalize.js\";\nimport { subscribeToTimeline, type TimelineSubscription } from \"./sync.js\";\nimport type { MatrixAdapterOptions, MatrixEventLike, MatrixRoomLike } from \"./types.js\";\n\nconst DEFAULT_FRESHNESS_MS = 60_000;\nconst INITIAL_SYNC_LIMIT = 10;\n\nexport class MatrixAdapter extends BasePlatformAdapter {\n readonly platform = \"matrix\" as const;\n private readonly opts: MatrixAdapterOptions;\n private client: MatrixSdkClient | undefined;\n private subscription: TimelineSubscription | undefined;\n private inboundHandler: ((event: GatewayMessageEvent) => Promise<void>) | undefined;\n private readonly aliasCache = new AliasCache();\n private connected = false;\n private readonly warnedEncrypted = new Set<string>();\n /** True only between disconnect() and the next connect() — see #12. */\n private tearingDown = false;\n\n /**\n * `fetch` for the SDK that leaves teardown aborts unsettled instead of\n * rejecting (#12).\n *\n * A request aborted while we are tearing the client down has no consumer left\n * that could act on the outcome, so an unsettled promise costs a continuation\n * and nothing else; the alternative is a rejection with no handler anywhere,\n * which ends the host process. It is scoped to the teardown window on purpose:\n * a consumer using the `getClient()` escape hatch (D421) may pass its own\n * abort signal to `search()` or `slidingSync()` and MUST still see those\n * rejections, so outside teardown every error propagates untouched.\n */\n private teardownSafeFetch(): typeof globalThis.fetch {\n const base = globalThis.fetch.bind(globalThis);\n return (input, init) =>\n base(input, init).catch((err: unknown) => {\n if (this.tearingDown && isAbortError(err)) {\n return new Promise<Response>(() => {\n /* deliberately never settles — see the doc comment */\n });\n }\n throw err;\n });\n }\n\n constructor(opts: MatrixAdapterOptions) {\n super();\n if (opts.homeserverUrl.length === 0) {\n throw new ConfigurationError({\n code: \"homeserver_url_required\",\n message: 'gateway-matrix: opts.homeserverUrl is empty (e.g. \"https://matrix.org\")',\n });\n }\n if (opts.accessToken.length === 0) {\n throw new ConfigurationError({\n code: \"access_token_required\",\n message:\n \"gateway-matrix: opts.accessToken is empty (Element → Settings → Help & About → Advanced → Access Token)\",\n });\n }\n if (opts.userId.length === 0 || !opts.userId.startsWith(\"@\")) {\n throw new ConfigurationError({\n code: \"user_id_required\",\n message: 'gateway-matrix: opts.userId must be a Matrix user id (e.g. \"@bot:matrix.org\")',\n });\n }\n this.opts = opts;\n }\n\n async connect(): Promise<boolean> {\n if (this.connected) return true;\n this.tearingDown = false;\n try {\n const cfg = {\n baseUrl: this.opts.homeserverUrl,\n accessToken: this.opts.accessToken,\n userId: this.opts.userId,\n fetchFn: this.teardownSafeFetch(),\n };\n const factory = this.opts.__clientFactory;\n this.client =\n factory === undefined\n ? (await loadMatrixSdk()).createClient(cfg)\n : (factory(cfg) as MatrixSdkClient);\n // Validate the credential BEFORE reporting success. `startClient` kicks\n // off the sync loop asynchronously and resolves whether or not the token\n // is any good — so connect() used to answer `true` for a token the server\n // rejects, leaving an operator with a healthy-looking adapter and total\n // silence. Every sibling adapter returns false here; this one did not,\n // and only a real homeserver could show it.\n await this.client.whoami();\n await this.client.startClient({ initialSyncLimit: INITIAL_SYNC_LIMIT });\n this.attachSync();\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-matrix] connect failed: ${msg}\\n`);\n return false;\n }\n }\n\n async disconnect(): Promise<void> {\n if (!this.connected) return;\n // Issue #12. `stopClient()` aborts the requests still in flight, and the\n // AbortError escapes as an UNHANDLED rejection — the rejecting promise is\n // the SDK's own `authedRequest` wrapper, which no caller catches and which\n // we cannot reach. Node has terminated on unhandled rejections by default\n // since v15, so an application calling disconnect() inside a reconnect loop\n // could be killed by its own clean shutdown. Measured against a real\n // homeserver: 7 occurrences in 8 connect/disconnect cycles.\n //\n // `teardownSafeFetch` closes it at the only seam the SDK offers. The flag is\n // set here, before the abort, and cleared by the next connect().\n this.tearingDown = true;\n this.subscription?.unsubscribe();\n this.subscription = undefined;\n this.client?.stopClient();\n this.client = undefined;\n this.connected = false;\n this.inboundHandler = undefined;\n this.aliasCache.clear();\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.client === undefined) {\n return {\n ok: false,\n error: { code: \"not_connected\", message: \"MatrixAdapter.connect() not called\" },\n };\n }\n try {\n const roomId = await this.aliasCache.resolve(this.client, out.channel.id);\n if (this.isEncrypted(roomId)) {\n this.warnEncryptedOnce(roomId);\n return {\n ok: false,\n error: {\n code: \"encrypted_room_unsupported\",\n message: `Matrix room ${roomId} is encrypted; E2EE deferred to v0.2`,\n },\n };\n }\n const res = await this.sendHonouringFormat(roomId, out);\n return { ok: true, messageId: res.event_id };\n } catch (err) {\n return mapMatrixError(err);\n }\n }\n\n /**\n * Send `out`, letting the caller's declared `format` decide the shape.\n *\n * Matrix carries markup in `formatted_body` and declares its type in `format`, whose only\n * value is `org.matrix.custom.html`. That declaration is a promise to every client that the\n * field IS HTML — so only `format: \"html\"` may use it.\n *\n * **`markdown` deliberately does not.** The first version of this method put the caller's\n * markdown into `formatted_body` and declared it HTML, which was worse than the bug it meant\n * to fix: `**bold**` still rendered as literal asterisks because markdown is not HTML, AND a\n * `<div>` anywhere in the text was parsed as a tag and dropped, so the reader received words\n * the sender never wrote and lost the ones they did. Caught in review; the test that\n * \"proved\" it was asserting the defect.\n *\n * So Matrix joins LINE, SMS and WhatsApp: it has no markdown mode, and the honest handling is\n * to say once that the declaration is being dropped rather than to fake it.\n *\n * Falls back to `sendTextMessage` when the client does not expose `sendMessage`: it is\n * optional on {@link MatrixSdkClient} because a consumer may inject a narrower double, and\n * losing the formatting is better than losing the message.\n *\n * @internal\n */\n private async sendHonouringFormat(\n roomId: string,\n out: OutboundMessage,\n ): Promise<{ event_id: string }> {\n const client = this.client as MatrixSdkClient;\n if (out.format !== \"html\" || client.sendMessage === undefined) {\n this.warnFormatUnsupported(out.format);\n return await client.sendTextMessage(roomId, out.text);\n }\n try {\n return await client.sendMessage(roomId, {\n msgtype: \"m.text\",\n body: out.text,\n format: \"org.matrix.custom.html\",\n formatted_body: out.text,\n });\n } catch (err) {\n // ADR-2: an undelivered message is worse than an unformatted one — the caller loses the\n // content and the user sees nothing, which is strictly worse than losing the markup.\n //\n // The discrimination is the whole guard. A bare `catch` would swallow an expired token as\n // a formatting problem and retry into the same 401, turning an actionable error into a\n // silent double failure. Only a request the server judged malformed is retried.\n if (!isMalformedRequest(err)) throw err;\n process.stderr.write(\n \"[gateway-matrix] homeserver rejected the formatted body; retrying as plain text\\n\",\n );\n return await client.sendTextMessage(roomId, out.text);\n }\n }\n\n /** Whether the \"no markdown mode here\" warning has already been emitted. */\n private warnedAboutFormat = false;\n\n /**\n * Say, once, that a declared `markdown` has nowhere to go on this platform.\n *\n * Matrix's only markup type is HTML. A caller declaring `markdown` is asking for something\n * the protocol does not have, and putting the markdown in the HTML field would corrupt it.\n *\n * @internal\n */\n private warnFormatUnsupported(format: OutboundMessage[\"format\"]): void {\n if (format === undefined || format === \"plain\" || format === \"html\") return;\n if (this.warnedAboutFormat) return;\n this.warnedAboutFormat = true;\n process.stderr.write(\n `[gateway-matrix] format=\"${format}\" was declared, and Matrix has no markdown mode — ` +\n \"its only markup type is HTML. Sending as plain text; this is logged once.\\n\",\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 (D421) — caller can drive matrix-js-sdk directly for advanced features. */\n getClient(): MatrixSdkClient | undefined {\n return this.client;\n }\n\n /** Used by tests to install a mock SDK client + flip connected flag. */\n _installClient(client: MatrixSdkClient): void {\n this.client = client;\n this.connected = true;\n this.attachSync();\n }\n\n private attachSync(): void {\n if (this.client === undefined) return;\n const client = this.client;\n const opts = {\n botUserId: this.opts.userId,\n freshnessWindowMs: this.opts.freshnessWindowMs ?? DEFAULT_FRESHNESS_MS,\n };\n this.subscription = subscribeToTimeline(\n client,\n (ev: MatrixEventLike, room: MatrixRoomLike) => {\n void this.dispatchTimelineEvent(ev, room).catch((err: unknown) => {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] dispatchTimelineEvent failed: ${m}\\n`);\n });\n },\n opts,\n );\n }\n\n private async dispatchTimelineEvent(event: MatrixEventLike, room: MatrixRoomLike): Promise<void> {\n if (this.isEncrypted(room.roomId)) {\n this.warnEncryptedOnce(room.roomId);\n return;\n }\n const normalized = matrixEventToMessageEvent(event, room);\n if (normalized === undefined) return;\n if (this.inboundHandler === undefined) return;\n try {\n await this.inboundHandler(normalized);\n } catch (err) {\n const m = err instanceof Error ? err.message : String(err);\n process.stderr.write(`[gateway-matrix] handler threw: ${m}\\n`);\n }\n }\n\n private isEncrypted(roomId: string): boolean {\n if (this.client === undefined) return false;\n if (this.client.isRoomEncrypted === undefined) return false;\n try {\n return this.client.isRoomEncrypted(roomId);\n } catch {\n return false;\n }\n }\n\n private warnEncryptedOnce(roomId: string): void {\n if (this.warnedEncrypted.has(roomId)) return;\n this.warnedEncrypted.add(roomId);\n process.stderr.write(\n `[gateway-matrix] room ${roomId} is end-to-end encrypted; skipping (E2EE deferred to v0.2)\\n`,\n );\n }\n\n /**\n * Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).\n *\n * One line over `runHandler`, which owns the containment: a handler is user code, its throw is\n * named as the handler's failure rather than the platform's, and delivery continues.\n */\n override async deliver(\n event: GatewayMessageEvent,\n ): Promise<\"ok\" | \"no_handler\" | \"handler_threw\"> {\n return this.runHandler(this.inboundHandler, event);\n }\n}\n\n/**\n * Narrow abort detection. `DOMException.ABORT_ERR` is 20; the message check\n * covers runtimes that report the abort without the standard name or code.\n */\nfunction isAbortError(err: unknown): boolean {\n if (typeof err !== \"object\" || err === null) return false;\n const e = err as { name?: unknown; code?: unknown; message?: unknown };\n if (e.name === \"AbortError\") return true;\n if (e.code === 20) return true;\n return typeof e.message === \"string\" && /aborted/i.test(e.message);\n}\n\ninterface MatrixRestError {\n httpStatus?: number;\n errcode?: string;\n message?: string;\n name?: string;\n}\n\n/**\n * Did the homeserver judge the REQUEST malformed, as opposed to refusing the sender?\n *\n * Narrow by construction: a 400 with `M_BAD_JSON` or `M_INVALID_PARAM` is the server saying it\n * could not parse what it was given. A 401, 403 or 429 is about who is asking or how often,\n * and retrying those without markup would fail identically while reporting the wrong cause.\n */\nfunction isMalformedRequest(err: unknown): boolean {\n const e = err as MatrixRestError;\n if (e.httpStatus !== 400) return false;\n return e.errcode === \"M_BAD_JSON\" || e.errcode === \"M_INVALID_PARAM\";\n}\n\n// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: error mapping ladder is exhaustive — each branch maps one Matrix errcode/HTTP status to one canonical code; splitting hurts traceability.\nfunction mapMatrixError(err: unknown): SendResult {\n const e = err as MatrixRestError;\n const status = e.httpStatus ?? 0;\n if (status === 429 || e.errcode === \"M_LIMIT_EXCEEDED\") {\n return { ok: false, error: { code: \"rate_limit\", message: e.message ?? \"Matrix rate limit\" } };\n }\n if (status === 401 || status === 403 || e.errcode === \"M_FORBIDDEN\") {\n return {\n ok: false,\n error: { code: \"permission_denied\", message: e.message ?? \"Matrix permission error\" },\n };\n }\n if (status === 404 || e.errcode === \"M_NOT_FOUND\") {\n return {\n ok: false,\n error: { code: \"not_found\", message: e.message ?? \"Matrix resource not found\" },\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"]}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@theokit/gateway-matrix",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Matrix protocol platform adapter for @theokit/gateway. ADRs D413-D421.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
@@ -44,12 +44,14 @@
|
|
|
44
44
|
}
|
|
45
45
|
},
|
|
46
46
|
"devDependencies": {
|
|
47
|
-
"@
|
|
47
|
+
"@stryker-mutator/core": "10",
|
|
48
|
+
"@stryker-mutator/vitest-runner": "10",
|
|
49
|
+
"@theokit/sdk": "^4.62.0",
|
|
48
50
|
"tsup": "^8.5.0",
|
|
49
|
-
"typescript": "
|
|
50
|
-
"vitest": "^4.1.
|
|
51
|
+
"typescript": "5.9.3",
|
|
52
|
+
"vitest": "^4.1.11",
|
|
51
53
|
"zod": "^4.0.0",
|
|
52
|
-
"@theokit/gateway": "0.
|
|
54
|
+
"@theokit/gateway": "0.9.0"
|
|
53
55
|
},
|
|
54
56
|
"publishConfig": {
|
|
55
57
|
"access": "public",
|
|
@@ -58,6 +60,7 @@
|
|
|
58
60
|
"scripts": {
|
|
59
61
|
"build": "tsup",
|
|
60
62
|
"typecheck": "tsc --noEmit",
|
|
61
|
-
"test": "vitest run"
|
|
63
|
+
"test": "vitest run",
|
|
64
|
+
"test:mutation": "stryker run"
|
|
62
65
|
}
|
|
63
66
|
}
|