@diegoaltoworks/chatter 0.59.0 → 0.61.0

package/README.md

@@ -26,7 +26,7 @@
 - ⚡ **High Performance**: Built on Hono with streaming support
 - 🛡️ **Security First**: Rate limiting, CORS, referrer checking, and input guardrails
 - 💸 **Usage Metering**: Per-caller and global daily caps for paid features, multi-instance safe, via `@diegoaltoworks/chatter/usage` ([guide](./docs/usage.md))
-- 💬 **Channels**: Built-in WhatsApp and Telegram transports plus a Channel SPI for plugging in any other one — allowlist/mute gates, reply rate-limiting, and a shared inbound pipeline every channel reuses ([WhatsApp](./docs/channels.md), [Telegram](./docs/telegram.md), [build your own](./docs/build-a-channel.md))
+- 💬 **Channels**: Built-in WhatsApp, Telegram and Matrix transports plus a Channel SPI for plugging in any other one — allowlist/mute gates, reply rate-limiting, and a shared inbound pipeline every channel reuses ([WhatsApp](./docs/channels.md), [Telegram](./docs/telegram.md), [Matrix](./docs/matrix.md), [build your own](./docs/build-a-channel.md))
 - 🧩 **Flows**: Multi-turn, schema-driven slot-filling for structured conversations, with hybrid keyword + LLM intent matching ([guide](./docs/flows.md))
 - 🖼️ **Images**: On-demand generation and editing with cache-before-spend ordering and optional Cloudinary upload ([guide](./docs/images.md))
 - 🎭 **Personas**: Windowed, per-contact prompt layers and named greetings from a JSON registry ([guide](./docs/personas.md))
@@ -103,6 +103,7 @@ Complete guides for setup, deployment, and integration — see
 - **[WhatsApp Channel](./docs/channels.md)** - Link a WhatsApp number as a transport
 - **[Building a Channel](./docs/build-a-channel.md)** - Plug in a new transport
 - **[Telegram Channel](./docs/telegram.md)** - Run a bot on the official Bot API, no extra dependency
+- **[Matrix Channel](./docs/matrix.md)** - Run a bot on the client-server API, no extra dependency (unencrypted rooms only)
 - **[Flows](./docs/flows.md)** - Multi-turn, schema-driven slot-filling flows
 - **[Images](./docs/images.md)** - Generate and cache images on demand
 - **[Conversation History](./docs/history.md)** - Structural, host-replaceable multi-turn context

package/dist/channels/index.js

@@ -262,6 +262,75 @@ ${ctx.join("\n\n")}`
   return { system, messages, context: ctx };
 }
 
+// src/history/compaction.ts
+var DEFAULT_TIMEOUT_MS = 8e3;
+var LOAD_ALL = Number.MAX_SAFE_INTEGER;
+var SUMMARY_PREFIX = "Summary of earlier conversation: ";
+function defaultSummarize(client, model) {
+  return async ({ turns }) => {
+    const transcript = turns.map((turn) => `${turn.role}: ${turn.content}`).join("\n");
+    const { content } = await answerOnce({
+      client,
+      system: "Summarize the conversation turns below into a short paragraph a reader would need to continue the conversation. Preserve names, facts, and decisions; drop pleasantries. Reply with the summary only, no preamble.",
+      messages: [{ role: "user", content: transcript }],
+      // No `answerFn`: compaction is an internal chatter operation, not a
+      // chat surface, so it must not conscript a caller's brain hook, which
+      // is shaped to answer the user, not to summarize on the engine's behalf.
+      mode: "public",
+      model
+    });
+    return content;
+  };
+}
+function createHistoryCompactor(deps, options) {
+  const { threshold, keep, logger } = options;
+  if (!Number.isInteger(threshold) || threshold < 1) {
+    throw new Error(`Invalid history compaction threshold: ${threshold}`);
+  }
+  if (!Number.isInteger(keep) || keep < 0 || keep >= threshold) {
+    throw new Error(`Invalid history compaction keep: ${keep}`);
+  }
+  const summarize = options.summarize ?? defaultSummarize(deps.client, options.model);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return {
+    async maybeCompact(store, conversationId) {
+      const turns = await store.load(conversationId, LOAD_ALL);
+      if (turns.length < threshold) return;
+      const older = turns.slice(0, turns.length - keep);
+      let summary;
+      let timer;
+      try {
+        summary = await Promise.race([
+          summarize({ conversationId, turns: older }),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("history compaction timed out")), timeoutMs);
+          })
+        ]);
+      } catch (error) {
+        logger?.error(
+          `history compaction summarize failed for "${conversationId}"; history left untouched`,
+          error
+        );
+        return;
+      } finally {
+        clearTimeout(timer);
+      }
+      const trimmed = summary.trim();
+      if (!trimmed) return;
+      const fresh = await store.load(conversationId, LOAD_ALL);
+      const recent = fresh.slice(older.length);
+      await store.clear(conversationId);
+      await store.append(conversationId, {
+        role: "assistant",
+        content: `${SUMMARY_PREFIX}${trimmed}`
+      });
+      for (const turn of recent) {
+        await store.append(conversationId, turn);
+      }
+    }
+  };
+}
+
 // src/channels/pipeline.ts
 var DEFAULT_HISTORY_LIMIT = 20;
 var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
@@ -292,6 +361,10 @@ function createInboundPipeline(deps, config) {
   const underGroupRateLimit = createSlidingWindowRateLimiter(group.max, group.windowMs, now);
   const underDmRateLimit = createSlidingWindowRateLimiter(dm.max, dm.windowMs, now);
   const mode = "public";
+  const compactor = config.history?.compaction ? createHistoryCompactor(
+    { client: deps.client },
+    { model: config.model, ...config.history.compaction }
+  ) : void 0;
   return async function handleInboundMessage(msg, turn) {
     const allowedChats = config.allowedChats ?? [];
     const action = decideChannelAction(msg, {
@@ -367,6 +440,14 @@ function createInboundPipeline(deps, config) {
       await config.history?.store.append(conversationId, { role: "assistant", content });
     }
     await turn.reply.sendAnswer(msg.chatId, content);
+    const history = config.history;
+    if (compactor && historyEnabled && history) {
+      try {
+        await compactor.maybeCompact(history.store, conversationId);
+      } catch (error) {
+        config.logger?.error(`history compaction failed for "${conversationId}"`, error);
+      }
+    }
     return { action: "reply", content };
   };
 }

package/dist/channels/index.mjs

@@ -229,6 +229,75 @@ ${ctx.join("\n\n")}`
   return { system, messages, context: ctx };
 }
 
+// src/history/compaction.ts
+var DEFAULT_TIMEOUT_MS = 8e3;
+var LOAD_ALL = Number.MAX_SAFE_INTEGER;
+var SUMMARY_PREFIX = "Summary of earlier conversation: ";
+function defaultSummarize(client, model) {
+  return async ({ turns }) => {
+    const transcript = turns.map((turn) => `${turn.role}: ${turn.content}`).join("\n");
+    const { content } = await answerOnce({
+      client,
+      system: "Summarize the conversation turns below into a short paragraph a reader would need to continue the conversation. Preserve names, facts, and decisions; drop pleasantries. Reply with the summary only, no preamble.",
+      messages: [{ role: "user", content: transcript }],
+      // No `answerFn`: compaction is an internal chatter operation, not a
+      // chat surface, so it must not conscript a caller's brain hook, which
+      // is shaped to answer the user, not to summarize on the engine's behalf.
+      mode: "public",
+      model
+    });
+    return content;
+  };
+}
+function createHistoryCompactor(deps, options) {
+  const { threshold, keep, logger } = options;
+  if (!Number.isInteger(threshold) || threshold < 1) {
+    throw new Error(`Invalid history compaction threshold: ${threshold}`);
+  }
+  if (!Number.isInteger(keep) || keep < 0 || keep >= threshold) {
+    throw new Error(`Invalid history compaction keep: ${keep}`);
+  }
+  const summarize = options.summarize ?? defaultSummarize(deps.client, options.model);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return {
+    async maybeCompact(store, conversationId) {
+      const turns = await store.load(conversationId, LOAD_ALL);
+      if (turns.length < threshold) return;
+      const older = turns.slice(0, turns.length - keep);
+      let summary;
+      let timer;
+      try {
+        summary = await Promise.race([
+          summarize({ conversationId, turns: older }),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("history compaction timed out")), timeoutMs);
+          })
+        ]);
+      } catch (error) {
+        logger?.error(
+          `history compaction summarize failed for "${conversationId}"; history left untouched`,
+          error
+        );
+        return;
+      } finally {
+        clearTimeout(timer);
+      }
+      const trimmed = summary.trim();
+      if (!trimmed) return;
+      const fresh = await store.load(conversationId, LOAD_ALL);
+      const recent = fresh.slice(older.length);
+      await store.clear(conversationId);
+      await store.append(conversationId, {
+        role: "assistant",
+        content: `${SUMMARY_PREFIX}${trimmed}`
+      });
+      for (const turn of recent) {
+        await store.append(conversationId, turn);
+      }
+    }
+  };
+}
+
 // src/channels/pipeline.ts
 var DEFAULT_HISTORY_LIMIT = 20;
 var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
@@ -259,6 +328,10 @@ function createInboundPipeline(deps, config) {
   const underGroupRateLimit = createSlidingWindowRateLimiter(group.max, group.windowMs, now);
   const underDmRateLimit = createSlidingWindowRateLimiter(dm.max, dm.windowMs, now);
   const mode = "public";
+  const compactor = config.history?.compaction ? createHistoryCompactor(
+    { client: deps.client },
+    { model: config.model, ...config.history.compaction }
+  ) : void 0;
   return async function handleInboundMessage(msg, turn) {
     const allowedChats = config.allowedChats ?? [];
     const action = decideChannelAction(msg, {
@@ -334,6 +407,14 @@ function createInboundPipeline(deps, config) {
       await config.history?.store.append(conversationId, { role: "assistant", content });
     }
     await turn.reply.sendAnswer(msg.chatId, content);
+    const history = config.history;
+    if (compactor && historyEnabled && history) {
+      try {
+        await compactor.maybeCompact(history.store, conversationId);
+      } catch (error) {
+        config.logger?.error(`history compaction failed for "${conversationId}"`, error);
+      }
+    }
     return { action: "reply", content };
   };
 }

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

@@ -0,0 +1,133 @@
+/**
+ * Matrix Client-Server API client — the whole transport layer of the Matrix
+ * channel, over plain `fetch`. No SDK, no optional peer dependency: the
+ * client-server API is JSON over HTTPS (plus one raw-bytes upload endpoint),
+ * so `./matrix` costs a consumer nothing beyond the package itself.
+ *
+ * Everything here is about the wire: envelopes, error mapping, sync polling,
+ * sending, media upload. Interpretation of a room event (mentions, DMs,
+ * reply-to) lives in `./updates` and `./channel`.
+ *
+ * The access token is a credential carried in an `Authorization: Bearer`
+ * header, never a query string, so it never lands in a URL an error message
+ * might echo back — but a homeserver's own error body could still quote it
+ * back verbatim (a malformed-token 401, say), so it is redacted the same
+ * defensive way the Telegram client redacts its token — see
+ * {@link redactToken}.
+ */
+export interface MatrixEvent {
+    type: string;
+    event_id: string;
+    sender: string;
+    origin_server_ts: number;
+    content: Record<string, unknown>;
+    unsigned?: Record<string, unknown>;
+}
+export interface MatrixRoomTimeline {
+    events: MatrixEvent[];
+    /**
+     * True when the server omitted earlier events for size — a bot only ever
+     * reads forward from its own `since` token, so a limited timeline just
+     * means "more happened than fit in this batch", not a gap it needs to
+     * backfill; every event actually included here is still handled normally.
+     */
+    limited?: boolean;
+    prev_batch?: string;
+}
+export interface MatrixJoinedRoom {
+    timeline: MatrixRoomTimeline;
+}
+export interface MatrixInvitedRoom {
+    invite_state?: {
+        events: Array<{
+            type: string;
+            sender?: string;
+            content?: unknown;
+        }>;
+    };
+}
+export interface MatrixAccountDataEvent {
+    type: string;
+    content: Record<string, unknown>;
+}
+export interface MatrixSyncResponse {
+    next_batch: string;
+    rooms?: {
+        join?: Record<string, MatrixJoinedRoom>;
+        invite?: Record<string, MatrixInvitedRoom>;
+    };
+    account_data?: {
+        events?: MatrixAccountDataEvent[];
+    };
+}
+/** A client-server API call that returned a non-2xx, or never completed. `retryAfterMs` carries `M_LIMIT_EXCEEDED`'s own wait instruction when the homeserver sent one. */
+export declare class MatrixApiError extends Error {
+    readonly errcode?: string;
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: {
+        errcode?: string;
+        status?: number;
+        retryAfterMs?: number;
+    });
+}
+/**
+ * Replaces every occurrence of `token` with `***`. An empty token is left
+ * alone: replacing "" would corrupt the message rather than protect
+ * anything.
+ */
+export declare function redactToken(text: string, token: string): string;
+export type MatrixMediaKind = "image" | "file" | "video" | "audio";
+/** What `ChannelSender.sendMedia` accepts for this channel. A bare string is shorthand for an already-uploaded `mxc://` URI or an https URL to fetch and re-upload. */
+export interface MatrixMediaPayload {
+    /** @default "image" */
+    kind?: MatrixMediaKind;
+    /** An `mxc://` content URI (sent as-is) or an https URL (fetched, then uploaded). */
+    url: string;
+    caption?: string;
+    /** @default derived from the URL's last path segment, or the media kind */
+    filename?: string;
+}
+export interface MatrixApiConfig {
+    /** Homeserver client-server API origin, e.g. `https://matrix.example.org`. */
+    homeserverUrl: string;
+    /** A logged-in bot user's access token. A credential — pass it from the environment, never commit it. */
+    accessToken: string;
+    /** Overridable for tests and for hosts routing through a proxy; defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+}
+export interface MatrixApi {
+    /** Raw call, for an endpoint this interface does not wrap. Rejects with {@link MatrixApiError} on any non-2xx response. */
+    call<T>(method: string, path: string, options?: {
+        body?: unknown;
+        query?: Record<string, string | number | undefined>;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    whoami(): Promise<{
+        userId: string;
+    }>;
+    sync(options: {
+        since?: string;
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<MatrixSyncResponse>;
+    /** A user's global account data of `type` (e.g. `m.direct`), or `undefined` if it was never set (`M_NOT_FOUND`). */
+    getAccountData<T>(userId: string, type: string): Promise<T | undefined>;
+    /** Sends an `m.room.message` (or any event type, via `eventType`) and returns its event id. */
+    sendEvent(roomId: string, content: Record<string, unknown>, options?: {
+        eventType?: string;
+    }): Promise<{
+        eventId: string;
+    }>;
+    /** Uploads raw bytes to the media repository and returns its `mxc://` content URI. */
+    uploadMedia(bytes: Uint8Array, contentType: string, filename?: string): Promise<{
+        contentUri: string;
+    }>;
+    /** Fetches `url`, uploads the bytes, and sends the resulting `m.room.message` — the whole `MatrixMediaPayload` -> delivered-event path. */
+    sendMedia(roomId: string, payload: unknown): Promise<{
+        eventId: string;
+    }>;
+    joinRoom(roomIdOrAlias: string): Promise<void>;
+}
+export declare function createMatrixApi(config: MatrixApiConfig): MatrixApi;
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/channels/matrix/api.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,98 @@
+/**
+ * Matrix client-server transport: a {@link Channel} that long-polls
+ * `/sync`, maps each room event into a `ChannelMessage`, and answers
+ * through the shared `createInboundPipeline` — the same gates, persona,
+ * buckets, history and `answerFn` seams every other channel uses.
+ *
+ * Deliberately the plain client-server HTTP API over `fetch`, not an SDK:
+ * no optional peer dependency, same as `../telegram`. That also means
+ * **no end-to-end encryption support** — an encrypted room's events arrive
+ * as opaque `m.room.encrypted` ciphertext this channel cannot decrypt, so
+ * it silently cannot see anything sent there. Use this channel only in
+ * unencrypted rooms; see docs/matrix.md for the full explanation and why
+ * that rules out most default-E2EE personal homeservers for DMs.
+ */
+import type { AnswerFn, TransformReply } from "../../core/answer";
+import type { BucketsFor } from "../../core/buckets";
+import { type Logger } from "../../core/logger";
+import type { RerankContext, RewriteQuery } from "../../core/pipeline";
+import type { HistoryCompactionOptions } from "../../history/compaction";
+import type { HistoryStore } from "../../history/types";
+import type { Channel } from "../index";
+import { type MatrixApi } from "./api";
+export interface MatrixChannelConfig {
+    /** Homeserver client-server API origin, e.g. `https://matrix.example.org`. */
+    homeserverUrl: string;
+    /** A logged-in bot user's access token. A credential — pass it from the environment, never commit it. */
+    accessToken: string;
+    /** Channel and sender-registry name. Override to run more than one bot in one process. @default "matrix" */
+    name?: string;
+    /** Group rooms eligible for a reply. Empty (default) = every room. Has no effect on DMs, which always reply. */
+    allowedChats?: string[];
+    answerFn?: AnswerFn;
+    bucketsFor?: BucketsFor;
+    /** Rewrites the retrieval query before it reaches the vector store — see `ChatterConfig.rewriteQuery`. Falls back to the server's own. */
+    rewriteQuery?: RewriteQuery;
+    /** Post-processes retrieved chunks before they're folded into the prompt — see `ChatterConfig.rerankContext`. Falls back to the server's own. */
+    rerankContext?: RerankContext;
+    /** Modifies or vetoes the produced reply before delivery — see `ChatterConfig.transformReply`. Falls back to the server's own. */
+    transformReply?: TransformReply;
+    model?: string;
+    /** Extra system-prompt section describing the delivery channel; passed through to `prepareChat`. @default "Channel: Matrix." */
+    channelHint?: string;
+    /** A throw/rejection is treated as "no persona" for that turn. `sender` is the namespaced `mx:<user id>` key. */
+    personaResolver?: (ctx: {
+        sender: string;
+        text: string;
+    }) => string | undefined | Promise<string | undefined>;
+    /** Off by default — the channel stays single-turn until a store is configured. */
+    history?: {
+        store: HistoryStore;
+        /** Most recent turns to load per reply. @default 20 */
+        limit?: number;
+        /**
+         * Excludes a sender from history entirely — see
+         * `InboundPipelineConfig.history.historyEnabledFor` in `./channels`.
+         * @default every sender is enabled
+         */
+        historyEnabledFor?: (sender: string) => boolean | Promise<boolean>;
+        /**
+         * Summarize-then-truncate compaction — see
+         * `InboundPipelineConfig.history.compaction` in `./channels`.
+         * @default off
+         */
+        compaction?: HistoryCompactionOptions;
+    };
+    muteRegex?: RegExp;
+    unmuteRegex?: RegExp;
+    /** Neutral, overridable acknowledgements — this module ships no bot personality; unset = silent mute/unmute. */
+    muteReply?: string;
+    unmuteReply?: string;
+    dmRateLimit?: {
+        max: number;
+        windowMs: number;
+    };
+    groupRateLimit?: {
+        max: number;
+        windowMs: number;
+    };
+    /** Auto-accept room invites, so the bot can actually receive messages in a room a user just invited it to. @default true */
+    autoJoin?: boolean;
+    /** @default 30000 */
+    syncTimeoutMs?: number;
+    /** Resume point for `/sync`. Omitted = an initial full sync (see docs/matrix.md on `since`-token persistence). */
+    initialSince?: string;
+    /** Called with each acknowledged `since` token, for a host that wants to persist it across restarts. */
+    onSince?: (since: string) => void;
+    /** Overridable for tests and for hosts routing through a proxy; defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Overridable for tests, which fake the client-server API instead of calling it; defaults to a `fetch` client over {@link MatrixChannelConfig.homeserverUrl}/{@link MatrixChannelConfig.accessToken}. */
+    api?: MatrixApi;
+    /** Overridable for tests; defaults to a `setTimeout`-based sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Logger for sync/gate diagnostics. Falls back to the host's `deps.logger`, then a console logger. */
+    logger?: Logger;
+}
+export declare function createMatrixChannel(config: MatrixChannelConfig): Channel;
+//# sourceMappingURL=channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/channels/matrix/channel.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,51 @@
+/**
+ * The per-sync-batch handling logic for the Matrix channel: room-invite
+ * auto-join, `m.direct` account-data tracking, event -> `ChannelMessage`
+ * mapping, and pipeline dispatch — the Matrix analogue of
+ * `../telegram/handler.ts`, adapted to a `/sync` response covering several
+ * rooms and events at once instead of one Telegram update.
+ */
+import type { Logger } from "../../core/logger";
+import type { InboundPipeline } from "../pipeline";
+import type { ChannelSender } from "../senders";
+import type { MatrixApi, MatrixSyncResponse } from "./api";
+import { type MatrixIdentity } from "./updates";
+export interface MatrixSyncHandlerDeps {
+    api: MatrixApi;
+    me: MatrixIdentity;
+    pipeline: InboundPipeline;
+    /** Group rooms eligible for a reply. Empty = every room. */
+    allowedChats: string[];
+    /**
+     * This session's own sent event ids, for reply-to-bot detection (see
+     * `./updates`'s `isReplyToBot`) — shared with, and appended to by, the
+     * `ChannelSender` this channel registers, so a reply sent outside a
+     * pipeline turn (a scheduler, a flow) is still recognised.
+     */
+    sentEventIds: Set<string>;
+    /** Auto-accept room invites so the bot can actually receive messages there. @default true */
+    autoJoin?: boolean;
+    /**
+     * The DM room set as of `start()` (see `./channel`'s upfront
+     * `getAccountData("m.direct")` fetch) — seeded here because an initial
+     * `/sync` response's `account_data` isn't guaranteed to repeat `m.direct`
+     * and a resumed sync (with `initialSince`) never carries it again unless
+     * it changes, so without this a restart would treat every known DM as an
+     * addressing-required group until the user's `m.direct` next changes.
+     */
+    initialDirectRooms?: ReadonlySet<string>;
+    logger: Logger;
+    /** Log-line prefix, e.g. `Matrix[@bot:example.org]`. */
+    label: string;
+}
+/**
+ * One `/sync` response -> zero or more pipeline turns, one per
+ * `m.room.message` event across every joined room in the batch. Builds its
+ * own allowlist-log dedup set, so each transport instance gets its own
+ * "skipped room" throttling rather than sharing (or fighting over) state
+ * with another.
+ */
+export declare function createMatrixSyncHandler(deps: MatrixSyncHandlerDeps): (response: MatrixSyncResponse) => Promise<void>;
+/** The `ChannelSender` every Matrix transport registers — text, media and reactions over the same `MatrixApi`. */
+export declare function createMatrixSender(api: MatrixApi, sentEventIds: Set<string>): ChannelSender;
+//# sourceMappingURL=handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/channels/matrix/handler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,KAAK,EAAE,eAAe,EAAsB,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAC3D,OAAO,EAEL,KAAK,cAAc,EAIpB,MAAM,WAAW,CAAC;AAmBnB,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,SAAS,CAAC;IACf,EAAE,EAAE,cAAc,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,4DAA4D;IAC5D,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;;;;OAKG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,qBAAqB,GAC1B,CAAC,QAAQ,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAgEjD;AAED,kHAAkH;AAClH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,aAAa,CAkB3F"}

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

@@ -0,0 +1,37 @@
+/**
+ * Matrix client-server transport — a {@link Channel} with NO optional peer
+ * dependency: the client-server API is JSON over HTTPS (plus one raw-bytes
+ * upload endpoint), reached with plain `fetch`, so this subpath costs a
+ * consumer nothing beyond the package itself.
+ *
+ * ```ts
+ * import { createMatrixChannel } from "@diegoaltoworks/chatter/matrix";
+ *
+ * await createServer({
+ *   ...,
+ *   channels: [
+ *     createMatrixChannel({
+ *       homeserverUrl: process.env.MATRIX_HOMESERVER_URL as string,
+ *       accessToken: process.env.MATRIX_ACCESS_TOKEN as string,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * **End-to-end encryption is not supported.** This channel only sees
+ * unencrypted rooms — see docs/matrix.md for the full explanation before
+ * relying on this for DMs, which most clients encrypt by default.
+ *
+ * Everything past turning a room event into a `ChannelMessage` runs through
+ * `./channels`' `createInboundPipeline`, shared with every other channel —
+ * see docs/matrix.md for configuration and docs/build-a-channel.md for the
+ * SPI this implements.
+ *
+ * @packageDocumentation
+ */
+export { createMatrixApi, type MatrixAccountDataEvent, type MatrixApi, type MatrixApiConfig, MatrixApiError, type MatrixEvent, type MatrixInvitedRoom, type MatrixJoinedRoom, type MatrixMediaKind, type MatrixMediaPayload, type MatrixRoomTimeline, type MatrixSyncResponse, redactToken, } from "./api";
+export { createMatrixChannel, type MatrixChannelConfig } from "./channel";
+export { createMatrixSender, createMatrixSyncHandler, type MatrixSyncHandlerDeps, } from "./handler";
+export { retryDelayMs, runMatrixSyncLoop, syncBackoffMs } from "./sync";
+export { directRoomIds, isReplyToBot, MAX_TRACKED_SENT_EVENTS, type MatrixIdentity, matrixSenderKey, mentionsBot, messageText, recordSentEventId, toChannelMessage, } from "./updates";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/matrix/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,WAAW,GACZ,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,KAAK,qBAAqB,GAC3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACxE,OAAO,EACL,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,KAAK,cAAc,EACnB,eAAe,EACf,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC"}