@diegoaltoworks/chatter 0.54.2 → 0.56.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 transport 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 guide](./docs/channels.md), [build your own](./docs/build-a-channel.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))
 - 🧩 **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))
@@ -102,6 +102,7 @@ Complete guides for setup, deployment, and integration — see
 - **[Personas](./docs/personas.md)** - Dynamic prompt layers and named greetings
 - **[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
 - **[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

@@ -160,6 +160,18 @@ async function answerOnce({
   }
   return completeOnce({ client, system, messages, temperature, model });
 }
+async function applyTransformReply(transformReply, input, logger) {
+  if (!transformReply) return input.text;
+  try {
+    return await transformReply(input);
+  } catch (error) {
+    logger?.error(
+      `transformReply threw for channel "${input.channel}"; sending the original reply`,
+      error
+    );
+    return input.text;
+  }
+}
 
 // src/core/buckets.ts
 function defaultBuckets(mode) {
@@ -295,7 +307,7 @@ function createInboundPipeline(deps, config) {
       channelHint: config.channelHint,
       buckets
     });
-    const { content } = await answerOnce({
+    const { content: produced } = await answerOnce({
       answerFn: config.answerFn,
       client: deps.client,
       system,
@@ -305,6 +317,11 @@ function createInboundPipeline(deps, config) {
       conversationId,
       model: config.model
     });
+    const content = await applyTransformReply(
+      config.transformReply,
+      { channel: config.channel ?? "channel", sender, conversationId, text: produced },
+      config.logger
+    );
     if (!content) {
       return { action: "ignore" };
     }

package/dist/channels/index.mjs

@@ -127,6 +127,18 @@ async function answerOnce({
   }
   return completeOnce({ client, system, messages, temperature, model });
 }
+async function applyTransformReply(transformReply, input, logger) {
+  if (!transformReply) return input.text;
+  try {
+    return await transformReply(input);
+  } catch (error) {
+    logger?.error(
+      `transformReply threw for channel "${input.channel}"; sending the original reply`,
+      error
+    );
+    return input.text;
+  }
+}
 
 // src/core/buckets.ts
 function defaultBuckets(mode) {
@@ -262,7 +274,7 @@ function createInboundPipeline(deps, config) {
       channelHint: config.channelHint,
       buckets
     });
-    const { content } = await answerOnce({
+    const { content: produced } = await answerOnce({
       answerFn: config.answerFn,
       client: deps.client,
       system,
@@ -272,6 +284,11 @@ function createInboundPipeline(deps, config) {
       conversationId,
       model: config.model
     });
+    const content = await applyTransformReply(
+      config.transformReply,
+      { channel: config.channel ?? "channel", sender, conversationId, text: produced },
+      config.logger
+    );
     if (!content) {
       return { action: "ignore" };
     }

package/dist/channels/pipeline.d.ts

@@ -14,8 +14,9 @@
  * re-derive it. See docs/build-a-channel.md for a worked example.
  */
 import type OpenAI from "openai";
-import type { AnswerFn } from "../core/answer";
+import type { AnswerFn, TransformReply } from "../core/answer";
 import type { BucketsFor } from "../core/buckets";
+import type { Logger } from "../core/logger";
 import type { PromptLoader } from "../core/prompts";
 import type { VectorStore } from "../core/retrieval";
 import type { HistoryStore } from "../history/types";
@@ -33,8 +34,15 @@ export interface InboundPipelineDeps {
     prompts: PromptLoader;
 }
 export interface InboundPipelineConfig {
+    /**
+     * This channel's identity for `transformReply` — e.g. "whatsapp",
+     * "telegram". @default "channel"
+     */
+    channel?: string;
     answerFn?: AnswerFn;
     bucketsFor?: BucketsFor;
+    /** Modifies or vetoes the produced reply before delivery — see `ChatterConfig.transformReply`. */
+    transformReply?: TransformReply;
     model?: string;
     /** Extra system-prompt section describing the delivery channel; passed through to `prepareChat`. */
     channelHint?: string;
@@ -65,6 +73,8 @@ export interface InboundPipelineConfig {
         windowMs: number;
     };
     now?: () => number;
+    /** Logs a `transformReply` throw; the original reply still sends. */
+    logger?: Logger;
 }
 export interface InboundTurn {
     /** Delivers this turn's gate ack / chat answer — see {@link InboundReplySender}. */

package/dist/channels/pipeline.d.ts.map

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

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

@@ -0,0 +1,122 @@
+/**
+ * Telegram Bot API client — the whole transport layer of the Telegram
+ * channel, over plain `fetch`. No SDK, no optional peer dependency: the Bot
+ * API is JSON over HTTPS, so `./telegram` costs a consumer nothing beyond the
+ * package itself.
+ *
+ * Everything here is about the wire: envelopes, error mapping, the 4096-char
+ * message limit. Interpretation of a message (mentions, gates, replies) lives
+ * in `./updates` and `./channel`.
+ *
+ * The bot token is a credential that appears in every request URL, so it is
+ * never allowed into an error message or a log line — see {@link redactToken}.
+ */
+/** Default Bot API origin. A self-hosted Bot API server sets its own via `baseUrl`. */
+export declare const TELEGRAM_API_BASE = "https://api.telegram.org";
+/** Bot API `sendMessage` hard limit, in UTF-16 code units. A longer text is rejected with HTTP 400. */
+export declare const TELEGRAM_TEXT_LIMIT = 4096;
+export interface TelegramUser {
+    id: number;
+    is_bot?: boolean;
+    username?: string;
+    first_name?: string;
+}
+export interface TelegramChat {
+    id: number;
+    type: "private" | "group" | "supergroup" | "channel";
+}
+/** Offsets/lengths are UTF-16 code units — the same units JS string indexing uses, so `text.slice(offset, offset + length)` is exact. */
+export interface TelegramMessageEntity {
+    type: string;
+    offset: number;
+    length: number;
+    /** Present on `text_mention` entities: a mention of a user who has no username. */
+    user?: TelegramUser;
+}
+export interface TelegramMessage {
+    message_id: number;
+    from?: TelegramUser;
+    chat: TelegramChat;
+    text?: string;
+    /** Photos/videos/documents carry their text here, with entities on `caption_entities`. */
+    caption?: string;
+    entities?: TelegramMessageEntity[];
+    caption_entities?: TelegramMessageEntity[];
+    reply_to_message?: {
+        message_id?: number;
+        from?: TelegramUser;
+    };
+}
+export interface TelegramUpdate {
+    update_id: number;
+    message?: TelegramMessage;
+}
+/** A Bot API call that did not return `ok: true`, or never completed. `retryAfterMs` carries Telegram's own flood-wait instruction when it sent one. */
+export declare class TelegramApiError extends Error {
+    readonly errorCode?: number;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: {
+        errorCode?: number;
+        retryAfterMs?: number;
+    });
+}
+/**
+ * Replaces every occurrence of the bot token with `***`. The token is part of
+ * the request URL, and a fetch failure (or a proxy's error body) can echo that
+ * URL back — logging it verbatim would leak full control of the bot into the
+ * host's logs. An empty token is left alone: replacing "" would corrupt the
+ * message rather than protect anything.
+ */
+export declare function redactToken(text: string, token: string): string;
+/**
+ * Splits `text` into chunks no longer than `limit`, preferring paragraph, then
+ * line, then word boundaries — a model's answer regularly runs past Telegram's
+ * 4096-char cap, and the Bot API's response to that is to reject the whole
+ * message, so an unsplit send loses the answer entirely rather than truncating
+ * it. Empty/blank input yields no chunks (nothing to send).
+ */
+export declare function splitTelegramText(text: string, limit?: number): string[];
+/** What `ChannelSender.sendMedia` accepts for this channel. A bare string is shorthand for a photo URL. */
+export interface TelegramMediaPayload {
+    /** @default "photo" */
+    kind?: "photo" | "document" | "video" | "audio";
+    /** An https URL or a Telegram `file_id` — the two forms the Bot API accepts without a multipart upload. */
+    url: string;
+    caption?: string;
+}
+/**
+ * Turns the registry's opaque `sendMedia` payload into a Bot API call.
+ * `ChannelSender.sendMedia` types its payload as `unknown` (payload shapes are
+ * transport-defined), so this is where that unknown is checked — a malformed
+ * payload throws here, which the sender registry reports as `false` rather
+ * than letting a caller's bad send crash it.
+ */
+export declare function toTelegramMediaRequest(chatId: string, payload: unknown): {
+    method: string;
+    body: Record<string, unknown>;
+};
+export interface TelegramApiConfig {
+    botToken: string;
+    /** Overridable for tests and for hosts routing through a proxy; defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** @default {@link TELEGRAM_API_BASE} */
+    baseUrl?: string;
+}
+export interface TelegramApi {
+    /** Raw call, for a method this interface does not wrap. Rejects with {@link TelegramApiError} on any non-`ok` result. */
+    call<T>(method: string, body?: Record<string, unknown>, signal?: AbortSignal): Promise<T>;
+    getMe(): Promise<TelegramUser>;
+    getUpdates(options: {
+        offset?: number;
+        timeoutSeconds: number;
+        signal?: AbortSignal;
+    }): Promise<TelegramUpdate[]>;
+    /** Splits at {@link TELEGRAM_TEXT_LIMIT}; only the first chunk threads onto `replyToMessageId`. */
+    sendMessage(chatId: string, text: string, options?: {
+        replyToMessageId?: number;
+    }): Promise<void>;
+    sendMedia(chatId: string, payload: unknown): Promise<void>;
+    setMessageReaction(chatId: string, messageId: number, emoji: string): Promise<void>;
+}
+export declare function createTelegramApi(config: TelegramApiConfig): TelegramApi;
+//# sourceMappingURL=api.d.ts.map

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

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

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

@@ -0,0 +1,82 @@
+/**
+ * Telegram Bot API transport: a {@link Channel} that long-polls `getUpdates`,
+ * maps each update into a `ChannelMessage`, and answers through the shared
+ * `createInboundPipeline` — the same gates, persona, buckets, history and
+ * `answerFn` seams every other channel uses.
+ *
+ * This is the second transport on the channel SPI, and unlike WhatsApp it
+ * needs no optional peer dependency, no session persistence, and no deploy
+ * lease: the Bot API is JSON over HTTPS and Telegram itself queues updates
+ * per bot token. It is deliberately self-contained — `start(deps)` has
+ * everything it needs, so there is no `customRoutes` wiring step (contrast
+ * `./channels/whatsapp/inbound.ts`, whose transport and interpretation are
+ * separate modules).
+ *
+ * One caveat worth knowing before choosing this over a user-mode client: a bot
+ * cannot start a conversation (the user must message it first), and in groups
+ * Telegram's privacy mode means it only receives messages that address it —
+ * which is the same policy `decideChannelAction` applies anyway.
+ */
+import type { AnswerFn, TransformReply } from "../../core/answer";
+import type { BucketsFor } from "../../core/buckets";
+import { type Logger } from "../../core/logger";
+import type { HistoryStore } from "../../history/types";
+import type { Channel } from "../index";
+import { type TelegramApi } from "./api";
+export interface TelegramChannelConfig {
+    /** From @BotFather. A credential — pass it from the environment, never commit it. */
+    botToken: string;
+    /** Channel and sender-registry name. Override to run more than one bot in one process. @default "telegram" */
+    name?: string;
+    /** Group chats eligible for a reply. Empty (default) = every group. Has no effect on DMs, which always reply. */
+    allowedChats?: string[];
+    answerFn?: AnswerFn;
+    bucketsFor?: BucketsFor;
+    /** 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: Telegram." */
+    channelHint?: string;
+    /** A throw/rejection is treated as "no persona" for that turn. `sender` is the namespaced `tg:<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;
+        limit?: number;
+    };
+    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;
+    };
+    /** @default 30 */
+    pollTimeoutSeconds?: number;
+    /** Resume point for `getUpdates`. Omitted = whatever Telegram still has queued (see docs/telegram.md). */
+    initialOffset?: number;
+    /** Called with each acknowledged offset, for a host that wants to persist it across restarts. */
+    onOffset?: (offset: number) => void;
+    /** Overridable for tests and for hosts routing through a proxy; defaults to `globalThis.fetch`. */
+    fetch?: typeof fetch;
+    /** Self-hosted Bot API server origin. */
+    apiBaseUrl?: string;
+    /** Overridable for tests, which fake the Bot API instead of calling it; defaults to a `fetch` client over {@link TelegramChannelConfig.botToken}. */
+    api?: TelegramApi;
+    /** Overridable for tests; defaults to a `setTimeout`-based sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Logger for poll/gate diagnostics. Falls back to the host's `deps.logger`, then a console logger. */
+    logger?: Logger;
+}
+export declare function createTelegramChannel(config: TelegramChannelConfig): Channel;
+//# sourceMappingURL=channel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../../src/channels/telegram/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAuB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAGxC,OAAO,EAAqB,KAAK,WAAW,EAAuB,MAAM,OAAO,CAAC;AAOjF,MAAM,WAAW,qBAAqB;IACpC,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,8GAA8G;IAC9G,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iHAAiH;IACjH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,kIAAkI;IAClI,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kIAAkI;IAClI,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4GAA4G;IAC5G,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,kFAAkF;IAClF,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gHAAgH;IAChH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAChD,cAAc,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,kBAAkB;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0GAA0G;IAC1G,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iGAAiG;IACjG,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,mGAAmG;IACnG,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qJAAqJ;IACrJ,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AASD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAkI5E"}

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

@@ -0,0 +1,26 @@
+/**
+ * Telegram Bot API transport — a {@link Channel} with NO optional peer
+ * dependency: the Bot API is JSON over HTTPS, reached with plain `fetch`, so
+ * this subpath costs a consumer nothing beyond the package itself.
+ *
+ * ```ts
+ * import { createTelegramChannel } from "@diegoaltoworks/chatter/telegram";
+ *
+ * await createServer({
+ *   ...,
+ *   channels: [createTelegramChannel({ botToken: process.env.TELEGRAM_BOT_TOKEN as string })],
+ * });
+ * ```
+ *
+ * Everything past turning an update into a `ChannelMessage` runs through
+ * `./channels`' `createInboundPipeline`, shared with every other channel — see
+ * docs/telegram.md for configuration and docs/build-a-channel.md for the SPI
+ * this implements.
+ *
+ * @packageDocumentation
+ */
+export { createTelegramApi, redactToken, splitTelegramText, TELEGRAM_API_BASE, TELEGRAM_TEXT_LIMIT, type TelegramApi, type TelegramApiConfig, TelegramApiError, type TelegramChat, type TelegramMediaPayload, type TelegramMessage, type TelegramMessageEntity, type TelegramUpdate, type TelegramUser, toTelegramMediaRequest, } from "./api";
+export { createTelegramChannel, type TelegramChannelConfig } from "./channel";
+export { type LongPollDeps, pollBackoffMs, retryDelayMs, runLongPoll } from "./poll";
+export { mentionsBot, messageEntities, messageText, nextOffset, type TelegramBotIdentity, telegramSenderKey, toChannelMessage, } from "./updates";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/telegram/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,sBAAsB,GACvB,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,qBAAqB,EAAE,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,KAAK,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrF,OAAO,EACL,WAAW,EACX,eAAe,EACf,WAAW,EACX,UAAU,EACV,KAAK,mBAAmB,EACxB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,WAAW,CAAC"}