@diegoaltoworks/chatter 0.60.0 → 0.62.0

package/dist/channels/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   isBlockedByAllowlist: () => isBlockedByAllowlist,
   isEffectivelyFromSelf: () => isEffectivelyFromSelf,
   isFromAnySession: () => isFromAnySession,
+  resolveBrainHooks: () => resolveBrainHooks,
   underReplyRateLimit: () => underReplyRateLimit
 });
 module.exports = __toCommonJS(index_exports);
@@ -163,7 +164,8 @@ async function answerOnce({
 async function applyTransformReply(transformReply, input, logger) {
   if (!transformReply) return input.text;
   try {
-    return await transformReply(input);
+    const result = await transformReply(input);
+    return typeof result === "string" ? result : null;
   } catch (error) {
     logger?.error(
       `transformReply threw for channel "${input.channel}"; sending the original reply`,
@@ -225,6 +227,7 @@ async function prepareChat({
   sender,
   rewriteQuery,
   rerankContext,
+  fallbackFn,
   logger
 }) {
   const lastUserMsg = lastUserMessage(messages);
@@ -241,21 +244,39 @@ async function prepareChat({
       logger?.error("rewriteQuery threw; falling back to the original query", error);
     }
   }
-  let ctx = await store.query(query, topK, buckets ?? defaultBuckets(mode));
+  const resolvedBuckets = buckets ?? defaultBuckets(mode);
+  const retrievedChunks = await store.query(query, topK, resolvedBuckets);
+  let ctx = retrievedChunks;
   if (rerankContext) {
     try {
-      const reranked = await rerankContext({ query, chunks: ctx });
+      const reranked = await rerankContext({ query, chunks: [...ctx] });
       if (Array.isArray(reranked) && reranked.every((c) => typeof c === "string")) ctx = reranked;
     } catch (error) {
       logger?.error("rerankContext threw; falling back to the original chunks", error);
     }
   }
+  let fallback;
+  if (ctx.length === 0 && fallbackFn) {
+    try {
+      const guidance = await fallbackFn({
+        query,
+        mode,
+        buckets: resolvedBuckets,
+        sender,
+        retrievedChunks
+      });
+      if (typeof guidance === "string" && guidance.trim()) fallback = guidance.trim();
+    } catch (error) {
+      logger?.error("fallbackFn threw; proceeding without fallback guidance", error);
+    }
+  }
   const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
   const hint = channelHint?.trim();
   const system = [
     prompts.baseSystemRules,
     persona,
     ...hint ? [hint] : [],
+    ...fallback ? [fallback] : [],
     `${label}:
 ${ctx.join("\n\n")}`
   ].join("\n\n");
@@ -263,7 +284,7 @@ ${ctx.join("\n\n")}`
 }
 
 // src/history/compaction.ts
-var DEFAULT_TIMEOUT_MS = 8e3;
+var COMPACTION_TIMEOUT_MS = 8e3;
 var LOAD_ALL = Number.MAX_SAFE_INTEGER;
 var SUMMARY_PREFIX = "Summary of earlier conversation: ";
 function defaultSummarize(client, model) {
@@ -291,7 +312,7 @@ function createHistoryCompactor(deps, options) {
     throw new Error(`Invalid history compaction keep: ${keep}`);
   }
   const summarize = options.summarize ?? defaultSummarize(deps.client, options.model);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs = options.timeoutMs ?? COMPACTION_TIMEOUT_MS;
   return {
     async maybeCompact(store, conversationId) {
       const turns = await store.load(conversationId, LOAD_ALL);
@@ -332,6 +353,16 @@ function createHistoryCompactor(deps, options) {
 }
 
 // src/channels/pipeline.ts
+function resolveBrainHooks(config, fallback) {
+  return {
+    answerFn: config.answerFn ?? fallback?.answerFn,
+    bucketsFor: config.bucketsFor ?? fallback?.bucketsFor,
+    rewriteQuery: config.rewriteQuery ?? fallback?.rewriteQuery,
+    rerankContext: config.rerankContext ?? fallback?.rerankContext,
+    fallbackFn: config.fallbackFn ?? fallback?.fallbackFn,
+    transformReply: config.transformReply ?? fallback?.transformReply
+  };
+}
 var DEFAULT_HISTORY_LIMIT = 20;
 var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
 var DEFAULT_DM_RATE_LIMIT = { max: 20, windowMs: 60 * 60 * 1e3 };
@@ -416,6 +447,7 @@ function createInboundPipeline(deps, config) {
       sender,
       rewriteQuery: config.rewriteQuery,
       rerankContext: config.rerankContext,
+      fallbackFn: config.fallbackFn,
       logger: config.logger
     });
     const { content: produced } = await answerOnce({
@@ -539,5 +571,6 @@ function createSenderRegistry(logger = createConsoleLogger()) {
   isBlockedByAllowlist,
   isEffectivelyFromSelf,
   isFromAnySession,
+  resolveBrainHooks,
   underReplyRateLimit
 });

package/dist/channels/index.mjs

@@ -130,7 +130,8 @@ async function answerOnce({
 async function applyTransformReply(transformReply, input, logger) {
   if (!transformReply) return input.text;
   try {
-    return await transformReply(input);
+    const result = await transformReply(input);
+    return typeof result === "string" ? result : null;
   } catch (error) {
     logger?.error(
       `transformReply threw for channel "${input.channel}"; sending the original reply`,
@@ -192,6 +193,7 @@ async function prepareChat({
   sender,
   rewriteQuery,
   rerankContext,
+  fallbackFn,
   logger
 }) {
   const lastUserMsg = lastUserMessage(messages);
@@ -208,21 +210,39 @@ async function prepareChat({
       logger?.error("rewriteQuery threw; falling back to the original query", error);
     }
   }
-  let ctx = await store.query(query, topK, buckets ?? defaultBuckets(mode));
+  const resolvedBuckets = buckets ?? defaultBuckets(mode);
+  const retrievedChunks = await store.query(query, topK, resolvedBuckets);
+  let ctx = retrievedChunks;
   if (rerankContext) {
     try {
-      const reranked = await rerankContext({ query, chunks: ctx });
+      const reranked = await rerankContext({ query, chunks: [...ctx] });
       if (Array.isArray(reranked) && reranked.every((c) => typeof c === "string")) ctx = reranked;
     } catch (error) {
       logger?.error("rerankContext threw; falling back to the original chunks", error);
     }
   }
+  let fallback;
+  if (ctx.length === 0 && fallbackFn) {
+    try {
+      const guidance = await fallbackFn({
+        query,
+        mode,
+        buckets: resolvedBuckets,
+        sender,
+        retrievedChunks
+      });
+      if (typeof guidance === "string" && guidance.trim()) fallback = guidance.trim();
+    } catch (error) {
+      logger?.error("fallbackFn threw; proceeding without fallback guidance", error);
+    }
+  }
   const persona = personaLayer?.trim() || (mode === "private" ? prompts.privatePersona : prompts.publicPersona);
   const hint = channelHint?.trim();
   const system = [
     prompts.baseSystemRules,
     persona,
     ...hint ? [hint] : [],
+    ...fallback ? [fallback] : [],
     `${label}:
 ${ctx.join("\n\n")}`
   ].join("\n\n");
@@ -230,7 +250,7 @@ ${ctx.join("\n\n")}`
 }
 
 // src/history/compaction.ts
-var DEFAULT_TIMEOUT_MS = 8e3;
+var COMPACTION_TIMEOUT_MS = 8e3;
 var LOAD_ALL = Number.MAX_SAFE_INTEGER;
 var SUMMARY_PREFIX = "Summary of earlier conversation: ";
 function defaultSummarize(client, model) {
@@ -258,7 +278,7 @@ function createHistoryCompactor(deps, options) {
     throw new Error(`Invalid history compaction keep: ${keep}`);
   }
   const summarize = options.summarize ?? defaultSummarize(deps.client, options.model);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs = options.timeoutMs ?? COMPACTION_TIMEOUT_MS;
   return {
     async maybeCompact(store, conversationId) {
       const turns = await store.load(conversationId, LOAD_ALL);
@@ -299,6 +319,16 @@ function createHistoryCompactor(deps, options) {
 }
 
 // src/channels/pipeline.ts
+function resolveBrainHooks(config, fallback) {
+  return {
+    answerFn: config.answerFn ?? fallback?.answerFn,
+    bucketsFor: config.bucketsFor ?? fallback?.bucketsFor,
+    rewriteQuery: config.rewriteQuery ?? fallback?.rewriteQuery,
+    rerankContext: config.rerankContext ?? fallback?.rerankContext,
+    fallbackFn: config.fallbackFn ?? fallback?.fallbackFn,
+    transformReply: config.transformReply ?? fallback?.transformReply
+  };
+}
 var DEFAULT_HISTORY_LIMIT = 20;
 var DEFAULT_GROUP_RATE_LIMIT = { max: 30, windowMs: 60 * 60 * 1e3 };
 var DEFAULT_DM_RATE_LIMIT = { max: 20, windowMs: 60 * 60 * 1e3 };
@@ -383,6 +413,7 @@ function createInboundPipeline(deps, config) {
       sender,
       rewriteQuery: config.rewriteQuery,
       rerankContext: config.rerankContext,
+      fallbackFn: config.fallbackFn,
       logger: config.logger
     });
     const { content: produced } = await answerOnce({
@@ -505,5 +536,6 @@ export {
   isBlockedByAllowlist,
   isEffectivelyFromSelf,
   isFromAnySession,
+  resolveBrainHooks,
   underReplyRateLimit
 };

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

@@ -0,0 +1,152 @@
+/**
+ * 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;
+}
+/**
+ * A state event as it arrives in an invite's `invite_state`: the homeserver
+ * strips it down to type/state_key/sender/content for a room the bot has not
+ * joined, so there is no `event_id` or `origin_server_ts` here the way there
+ * is on a timeline event.
+ */
+export interface MatrixStrippedStateEvent {
+    type: string;
+    state_key?: string;
+    sender?: string;
+    content?: Record<string, unknown>;
+}
+export interface MatrixInvitedRoom {
+    invite_state?: {
+        events: MatrixStrippedStateEvent[];
+    };
+}
+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 under {@link MatrixApiConfig.maxMediaBytes}, then uploaded). Any other scheme is rejected. */
+    url: string;
+    caption?: string;
+    /** @default derived from the URL's last path segment, or the media kind */
+    filename?: string;
+}
+/**
+ * Default ceiling on a fetched media source. `sendMedia` is reachable from a
+ * scheduler, a flow or an `answerFn` tool call, so its URL is not necessarily
+ * one an operator chose: an unbounded fetch would let whatever produced that
+ * URL decide how much memory this process allocates.
+ */
+export declare const DEFAULT_MAX_MEDIA_BYTES: number;
+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;
+    /** Cap on the bytes `sendMedia` will pull from a remote https URL before uploading. @default 25 MiB */
+    maxMediaBytes?: number;
+}
+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>;
+    /** Replaces a user's global account data of `type`. Whole-document semantics: the homeserver stores exactly what is sent, so merge before calling. */
+    setAccountData(userId: string, type: string, content: Record<string, unknown>): Promise<void>;
+    /** 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,46 @@
+/**
+ * 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 { Channel } from "../index";
+import { type PollingChannelConfig } from "../polling";
+import { type MatrixApi } from "./api";
+export interface MatrixChannelConfig extends PollingChannelConfig {
+    /** 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;
+    /** 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>;
+    /** 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;
+    /** Cap on the bytes a `sendMedia` https URL may pull before upload. @default 25 MiB */
+    maxMediaBytes?: number;
+    /** 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;
+}
+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":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC,OAAO,EAAgB,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAQxD,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,yGAAyG;IACzG,WAAW,EAAE,MAAM,CAAC;IACpB,4GAA4G;IAC5G,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gIAAgI;IAChI,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iHAAiH;IACjH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvD,4HAA4H;IAC5H,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kHAAkH;IAClH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wGAAwG;IACxG,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0MAA0M;IAC1M,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CA8HxE"}

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

@@ -0,0 +1,58 @@
+/**
+ * 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 MatrixDirectMapping, 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.
+     * Gated by {@link MatrixSyncHandlerDeps.allowedChats} when that is set:
+     * an invite is an unauthenticated request from any user on any federated
+     * homeserver, so a configured allowlist governs which rooms the bot will
+     * join, not just which ones it will answer in.
+     * @default true
+     */
+    autoJoin?: boolean;
+    /**
+     * The bot's own `m.direct` mapping 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 it next changes.
+     */
+    initialDirect?: MatrixDirectMapping;
+    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,EAIL,KAAK,mBAAmB,EACxB,KAAK,cAAc,EAKpB,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;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,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,CAsGjD;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, DEFAULT_MAX_MEDIA_BYTES, type MatrixAccountDataEvent, type MatrixApi, type MatrixApiConfig, MatrixApiError, type MatrixEvent, type MatrixInvitedRoom, type MatrixJoinedRoom, type MatrixMediaKind, type MatrixMediaPayload, type MatrixRoomTimeline, type MatrixStrippedStateEvent, 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 { directInviteFrom, directMappingFromEvents, directMappingRooms, directRoomIds, isReplyToBot, MAX_TRACKED_SENT_EVENTS, type MatrixDirectMapping, type MatrixIdentity, matrixSenderKey, mentionsBot, messageText, recordSentEventId, toChannelMessage, toDirectMapping, withDirectRoom, } 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,uBAAuB,EACvB,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,wBAAwB,EAC7B,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,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,eAAe,EACf,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC"}