@diegoaltoworks/chatter 0.60.0 → 0.61.0

package/dist/channels/matrix/sync.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The `/sync` long-poll loop, isolated from both the HTTP client and the
+ * channel so its failure behaviour is testable without either — the same
+ * shape as `../telegram/poll.ts`'s `runLongPoll`, adapted to Matrix's
+ * `since`-token pagination instead of an acknowledged offset.
+ *
+ * The property that matters: a homeserver that is down, rate-limiting, or
+ * rejecting the token must never turn into a tight retry loop. Every
+ * failure backs off exponentially, and `M_LIMIT_EXCEEDED`'s own
+ * `retry_after_ms` wins over that backoff when the homeserver sends one.
+ */
+import { type Logger } from "../../core/logger";
+import { type MatrixSyncResponse } from "./api";
+/** Exponential backoff: 2s, 4s, 8s ... capped at a minute. `failures` is the count including the one just seen. */
+export declare function syncBackoffMs(failures: number): number;
+/**
+ * How long to wait after a failed sync. `M_LIMIT_EXCEEDED`'s
+ * `retry_after_ms` is an instruction, not a hint — honour it verbatim even
+ * when it exceeds the backoff cap, because syncing again sooner just
+ * extends the rate-limit window.
+ */
+export declare function retryDelayMs(error: unknown, failures: number): number;
+export interface MatrixSyncLoopDeps {
+    /** One `/sync` call. Rejections are backed off; they never end the loop. */
+    sync(since: string | undefined): Promise<MatrixSyncResponse>;
+    /** Per-batch work. A throw is logged and skipped — one bad batch never stops the loop. */
+    handleSync(response: MatrixSyncResponse): Promise<void>;
+    /** Checked before every sync, and again after a failure, so `stop()` cuts the loop instead of sleeping out a backoff first. */
+    isStopped(): boolean;
+    /** Overridable for tests; a real channel passes a `setTimeout`-based sleep. */
+    sleep(ms: number): Promise<void>;
+    /** Where this loop's `since` token resumes from. Omitted = an initial full sync. */
+    initialSince?: string;
+    /** Called with each newly acknowledged `since` token, for a host that persists it. */
+    onSince?(since: string): void;
+    logger?: Logger;
+    /** Prefix for log lines, e.g. `Matrix[@bot:example.org]`. */
+    label?: string;
+}
+/**
+ * Syncs until `isStopped()`, resolving with the last `since` token reached
+ * (what a restart would resume from).
+ *
+ * The token advances BEFORE the batch is handled, matching the Telegram
+ * poll loop's offset-first ordering: a handler that throws on one bad
+ * batch must not make the homeserver redeliver it forever, which would
+ * wedge the loop on a single poison event and starve every later one.
+ */
+export declare function runMatrixSyncLoop(deps: MatrixSyncLoopDeps): Promise<string | undefined>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/channels/matrix/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/channels/matrix/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAKhE,mHAAmH;AACnH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC7D,0FAA0F;IAC1F,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,+HAA+H;IAC/H,SAAS,IAAI,OAAO,CAAC;IACrB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiC7F"}

package/dist/channels/matrix/updates.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Matrix room event -> {@link ChannelMessage}: the transport's own half of
+ * the channel contract (see docs/build-a-channel.md), kept pure so mention,
+ * reply-to and DM detection are testable without a network or a running
+ * channel.
+ *
+ * Addressing parity with the other built-in channels is the point of this
+ * module. WhatsApp and Telegram both resolve "was the bot addressed?" from
+ * transport-native structures; Matrix resolves it from the stable
+ * `m.mentions` field (MSC3952, in the spec since v1.7) with a pill-in-HTML
+ * fallback for clients that only set that. The gate policy that consumes
+ * those booleans (`decideChannelAction`) is identical for every channel.
+ */
+import type { ChannelMessage } from "../gates";
+import type { MatrixAccountDataEvent, MatrixEvent } from "./api";
+/** The bot's own identity, as `whoami` reports it. */
+export interface MatrixIdentity {
+    userId: string;
+}
+interface MatrixMentions {
+    user_ids?: string[];
+    room?: boolean;
+}
+interface MatrixInReplyTo {
+    event_id?: string;
+}
+interface MatrixMessageContent {
+    msgtype?: string;
+    body?: string;
+    format?: string;
+    formatted_body?: string;
+    "m.mentions"?: MatrixMentions;
+    "m.relates_to"?: {
+        "m.in_reply_to"?: MatrixInReplyTo;
+    };
+}
+/** The message text, or "" for an event this channel doesn't render as text (a redaction, a non-text msgtype with no body). */
+export declare function messageText(content: MatrixMessageContent): string;
+export declare function mentionsBot(content: MatrixMessageContent, me: MatrixIdentity): boolean;
+/**
+ * Was this message a reply to one the bot sent? `sentEventIds` is the
+ * session's own record of event ids it has sent (see `./channel`) — Matrix
+ * has no cheap "who sent event X" lookup without fetching that event, and a
+ * bot only ever needs to recognise its OWN messages, which it already knows
+ * without asking the server.
+ */
+export declare function isReplyToBot(content: MatrixMessageContent, sentEventIds: ReadonlySet<string>): boolean;
+/** How many of the session's own sent event ids {@link isReplyToBot} remembers — bounded so a long-running bot's memory doesn't grow with every message it ever sent. */
+export declare const MAX_TRACKED_SENT_EVENTS = 500;
+/** Records `eventId` as one of ours, evicting the oldest entry first once the set is at capacity (`Set` iterates in insertion order, so the first value is the oldest). */
+export declare function recordSentEventId(sentEventIds: Set<string>, eventId: string): void;
+/**
+ * Room ids the homeserver's `m.direct` account data lists as direct
+ * messages, across every peer — the canonical way a Matrix client (and so a
+ * bot) tells a DM from a group: there is no per-room "this is a DM" flag.
+ * A room absent from this set is treated as a group and needs addressing,
+ * the safer default when a client never populated `m.direct` for it.
+ */
+export declare function directRoomIds(accountDataEvents: MatrixAccountDataEvent[]): Set<string>;
+/**
+ * The {@link ChannelMessage} for a timeline event, or `undefined` when
+ * there is nothing for a chat pipeline to look at: not an `m.room.message`
+ * (a reaction, a membership change, an encrypted event this channel can't
+ * decrypt), or one with no `msgtype` at all (a redacted message).
+ */
+export declare function toChannelMessage(roomId: string, event: MatrixEvent, me: MatrixIdentity, directRooms: ReadonlySet<string>, sentEventIds: ReadonlySet<string>): ChannelMessage | undefined;
+/**
+ * A stable identity key for `bucketsFor`/`personaResolver`/`answerFn`.
+ * Namespaced so a bare Matrix user id (which is itself already `@user:
+ * server.tld`, unlike Telegram's bare numeral) never collides with another
+ * channel's key when a host shares persona/spend state across channels.
+ */
+export declare function matrixSenderKey(userId: string): string;
+export {};
+//# sourceMappingURL=updates.d.ts.map

package/dist/channels/matrix/updates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updates.d.ts","sourceRoot":"","sources":["../../../src/channels/matrix/updates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEjE,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,cAAc;IACtB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,UAAU,eAAe;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,oBAAoB;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,cAAc,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,eAAe,CAAA;KAAE,CAAC;CACxD;AAED,+HAA+H;AAC/H,wBAAgB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAEjE;AAiCD,wBAAgB,WAAW,CAAC,OAAO,EAAE,oBAAoB,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAQtF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,OAAO,CAGT;AAED,yKAAyK;AACzK,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,2KAA2K;AAC3K,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMlF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,iBAAiB,EAAE,sBAAsB,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAYtF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAClB,EAAE,EAAE,cAAc,EAClB,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,GAChC,cAAc,GAAG,SAAS,CAe5B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegoaltoworks/chatter",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "Embeddable AI chatbot framework with RAG, authentication, and customizable widgets",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -68,6 +68,11 @@
       "import": "./dist/channels/telegram/index.mjs",
       "require": "./dist/channels/telegram/index.js"
     },
+    "./matrix": {
+      "types": "./dist/channels/matrix/index.d.ts",
+      "import": "./dist/channels/matrix/index.mjs",
+      "require": "./dist/channels/matrix/index.js"
+    },
     "./images": {
       "types": "./dist/images/index.d.ts",
       "import": "./dist/images/index.mjs",
@@ -88,7 +93,7 @@
   ],
   "scripts": {
     "dev": "bun --watch src/index.ts",
-    "build": "bun run build:clean && bun run build:types && bun run build:esm && bun run build:cjs && bun run build:server && bun run build:mcp && bun run build:usage && bun run build:history && bun run build:personas && bun run build:channels && bun run build:whatsapp && bun run build:telegram && bun run build:flows && bun run build:images && bun run build:scheduler && bun run build:bin && bun run build:client && bun run build:copy-client",
+    "build": "bun run build:clean && bun run build:types && bun run build:esm && bun run build:cjs && bun run build:server && bun run build:mcp && bun run build:usage && bun run build:history && bun run build:personas && bun run build:channels && bun run build:whatsapp && bun run build:telegram && bun run build:matrix && bun run build:flows && bun run build:images && bun run build:scheduler && bun run build:bin && bun run build:client && bun run build:copy-client",
     "build:clean": "rm -rf dist",
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "build:esm": "esbuild src/index.ts --bundle --format=esm --outfile=dist/index.mjs --external:@hono/node-server --external:hono --external:openai --external:@libsql/client --external:jose --external:@modelcontextprotocol/sdk --external:zod --platform=node --target=node24",
@@ -101,6 +106,7 @@
     "build:channels": "esbuild src/channels/index.ts --bundle --format=esm --outfile=dist/channels/index.mjs --external:hono --external:openai --external:@libsql/client --platform=node --target=node24 && esbuild src/channels/index.ts --bundle --format=cjs --outfile=dist/channels/index.js --external:hono --external:openai --external:@libsql/client --platform=node --target=node24",
     "build:whatsapp": "esbuild src/channels/whatsapp/index.ts --bundle --format=esm --outfile=dist/channels/whatsapp/index.mjs --external:@libsql/client --external:@whiskeysockets/baileys --platform=node --target=node24 && esbuild src/channels/whatsapp/index.ts --bundle --format=cjs --outfile=dist/channels/whatsapp/index.js --external:@libsql/client --external:@whiskeysockets/baileys --platform=node --target=node24",
     "build:telegram": "esbuild src/channels/telegram/index.ts --bundle --format=esm --outfile=dist/channels/telegram/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/channels/telegram/index.ts --bundle --format=cjs --outfile=dist/channels/telegram/index.js --external:@libsql/client --external:openai --platform=node --target=node24",
+    "build:matrix": "esbuild src/channels/matrix/index.ts --bundle --format=esm --outfile=dist/channels/matrix/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/channels/matrix/index.ts --bundle --format=cjs --outfile=dist/channels/matrix/index.js --external:@libsql/client --external:openai --platform=node --target=node24",
     "build:flows": "esbuild src/flows/index.ts --bundle --format=esm --outfile=dist/flows/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/flows/index.ts --bundle --format=cjs --outfile=dist/flows/index.js --external:@libsql/client --external:openai --platform=node --target=node24",
     "build:images": "esbuild src/images/index.ts --bundle --format=esm --outfile=dist/images/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/images/index.ts --bundle --format=cjs --outfile=dist/images/index.js --external:@libsql/client --external:openai --platform=node --target=node24",
     "build:scheduler": "esbuild src/scheduler/index.ts --bundle --format=esm --outfile=dist/scheduler/index.mjs --external:@libsql/client --external:openai --platform=node --target=node24 && esbuild src/scheduler/index.ts --bundle --format=cjs --outfile=dist/scheduler/index.js --external:@libsql/client --external:openai --platform=node --target=node24",