@mono-agent/telegram-adapter 0.1.0

package/dist/long-poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"long-poller.d.ts","sourceRoot":"","sources":["../src/long-poller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAId,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,gCAAgC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjE,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,cAAc,CAAC;IACpB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,OAAO,CAAC,EAAE,gCAAgC,CAAC;IAC3C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,MAAM,CAAC,EAAE,wBAAwB,CAAC;CACnC;AAED,MAAM,WAAW,8BAA8B;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAOD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IACtD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyD;IACjF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAC9D,OAAO,CAAC,gBAAgB,CAAqB;gBAEjC,OAAO,EAAE,yBAAyB;IAoC9C,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAEnC;IAEK,KAAK,CAAC,OAAO,GAAE,8BAAmC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkClE,QAAQ,CAAC,OAAO,GAAE,6BAAkC,GAAG,OAAO,CAAC,MAAM,CAAC;IA0B5E,OAAO,CAAC,qBAAqB;YAcf,aAAa;CAgB5B"}

package/dist/long-poller.js

@@ -0,0 +1,156 @@
+const DEFAULT_LIMIT = 100;
+const DEFAULT_TIMEOUT_SECONDS = 30;
+const DEFAULT_INITIAL_BACKOFF_MS = 500;
+const DEFAULT_MAX_BACKOFF_MS = 10_000;
+export class TelegramLongPoller {
+    api;
+    adapter;
+    limit;
+    timeoutSeconds;
+    allowedUpdates;
+    deleteWebhookOnStart;
+    dropPendingUpdates;
+    initialBackoffMs;
+    maxBackoffMs;
+    onError;
+    logger;
+    nextUpdateOffset;
+    constructor(options) {
+        if (options.api === undefined) {
+            throw new TypeError("TelegramLongPoller requires a Telegram Bot API client.");
+        }
+        if (typeof options.adapter?.handleUpdate !== "function") {
+            throw new TypeError("TelegramLongPoller requires an adapter with handleUpdate().");
+        }
+        this.api = options.api;
+        this.adapter = options.adapter;
+        this.limit = options.limit ?? DEFAULT_LIMIT;
+        this.timeoutSeconds = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+        this.allowedUpdates = options.allowedUpdates?.slice();
+        this.deleteWebhookOnStart = options.deleteWebhookOnStart === true;
+        this.dropPendingUpdates = options.dropPendingUpdates === true;
+        this.initialBackoffMs =
+            options.backoff?.initialMs ?? DEFAULT_INITIAL_BACKOFF_MS;
+        this.maxBackoffMs = options.backoff?.maxMs ?? DEFAULT_MAX_BACKOFF_MS;
+        this.onError = options.onError;
+        this.logger = options.logger;
+        this.nextUpdateOffset = options.initialOffset;
+        if (!Number.isInteger(this.limit) || this.limit < 1 || this.limit > 100) {
+            throw new RangeError("TelegramLongPoller limit must be an integer between 1 and 100.");
+        }
+        if (!Number.isFinite(this.timeoutSeconds) || this.timeoutSeconds < 0) {
+            throw new RangeError("TelegramLongPoller timeoutSeconds must be non-negative.");
+        }
+        if (!Number.isFinite(this.initialBackoffMs) || this.initialBackoffMs < 0) {
+            throw new RangeError("TelegramLongPoller initial backoff must be non-negative.");
+        }
+        if (!Number.isFinite(this.maxBackoffMs) || this.maxBackoffMs < this.initialBackoffMs) {
+            throw new RangeError("TelegramLongPoller max backoff must be at least the initial backoff.");
+        }
+    }
+    get nextOffset() {
+        return this.nextUpdateOffset;
+    }
+    async start(options = {}) {
+        if (isSignalAborted(options.signal)) {
+            return;
+        }
+        if (this.deleteWebhookOnStart) {
+            await this.deleteWebhook(options.signal);
+        }
+        let backoffMs = this.initialBackoffMs;
+        while (!isSignalAborted(options.signal)) {
+            try {
+                const pollOptions = {};
+                if (options.signal !== undefined) {
+                    pollOptions.signal = options.signal;
+                }
+                await this.pollOnce(pollOptions);
+                backoffMs = this.initialBackoffMs;
+            }
+            catch (error) {
+                if (isSignalAborted(options.signal) || isAbortError(error)) {
+                    return;
+                }
+                this.logger?.warn?.("Telegram long polling failed; backing off.", {
+                    error: error instanceof Error ? error.message : String(error),
+                    backoffMs,
+                });
+                await this.onError?.(error);
+                await abortableDelay(backoffMs, options.signal);
+                backoffMs = Math.min(this.maxBackoffMs, Math.max(backoffMs * 2, 1));
+            }
+        }
+    }
+    async pollOnce(options = {}) {
+        if (isSignalAborted(options.signal)) {
+            throw new DOMException("Telegram polling was aborted.", "AbortError");
+        }
+        const params = this.buildGetUpdatesParams();
+        const requestOptions = {};
+        if (options.signal !== undefined) {
+            requestOptions.signal = options.signal;
+        }
+        const updates = await this.api.getUpdates(params, requestOptions);
+        let handled = 0;
+        for (const update of updates) {
+            if (isSignalAborted(options.signal)) {
+                throw new DOMException("Telegram polling was aborted.", "AbortError");
+            }
+            await this.adapter.handleUpdate(update);
+            this.nextUpdateOffset = update.update_id + 1;
+            handled += 1;
+        }
+        return handled;
+    }
+    buildGetUpdatesParams() {
+        const params = {
+            limit: this.limit,
+            timeout: this.timeoutSeconds,
+        };
+        if (this.nextUpdateOffset !== undefined) {
+            params.offset = this.nextUpdateOffset;
+        }
+        if (this.allowedUpdates !== undefined) {
+            params.allowed_updates = this.allowedUpdates;
+        }
+        return params;
+    }
+    async deleteWebhook(signal) {
+        if (typeof this.api.deleteWebhook !== "function") {
+            throw new TypeError("TelegramLongPoller deleteWebhookOnStart requires api.deleteWebhook().");
+        }
+        const params = {
+            drop_pending_updates: this.dropPendingUpdates,
+        };
+        const requestOptions = {};
+        if (signal !== undefined) {
+            requestOptions.signal = signal;
+        }
+        await this.api.deleteWebhook(params, requestOptions);
+    }
+}
+function isAbortError(error) {
+    return (error instanceof DOMException && error.name === "AbortError") || (error instanceof Error && error.name === "AbortError");
+}
+function isSignalAborted(signal) {
+    return signal?.aborted === true;
+}
+function abortableDelay(ms, signal) {
+    if (ms <= 0 || signal?.aborted === true) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=long-poller.js.map

package/dist/long-poller.js.map

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

package/dist/message-stream.d.ts

@@ -0,0 +1,54 @@
+import type { AgentMessageStream as AgentMessageStreamBase } from "@mono-agent/agent-contracts";
+import type { TelegramBotApi, TelegramChatId } from "./types.js";
+export interface AgentMessageStream extends AgentMessageStreamBase {
+    status(text: string): Promise<void>;
+    append(delta: string): Promise<void>;
+    replace(text: string): Promise<void>;
+    finish(finalText?: string): Promise<void>;
+}
+export interface TelegramMessageStreamOptions {
+    api: TelegramBotApi;
+    chatId: TelegramChatId;
+    initialStatusText?: string;
+    editDebounceMs?: number;
+    maxMessageChars?: number;
+    replyToMessageId?: number;
+    logger?: TelegramMessageStreamLogger;
+}
+export interface TelegramMessageStreamLogger {
+    debug?(message: string, metadata?: Record<string, unknown>): void;
+    warn?(message: string, metadata?: Record<string, unknown>): void;
+    error?(message: string, metadata?: Record<string, unknown>): void;
+}
+export declare class TelegramMessageStream implements AgentMessageStream {
+    private readonly api;
+    private readonly chatId;
+    private readonly initialStatusText;
+    private readonly editDebounceMs;
+    private readonly maxMessageChars;
+    private readonly replyToMessageId;
+    private readonly logger;
+    private currentText;
+    private statusText;
+    private sentMessage;
+    private sendMessagePromise;
+    private editTimer;
+    private inFlightEdit;
+    private lastAsyncError;
+    private finished;
+    constructor(options: TelegramMessageStreamOptions);
+    status(text: string): Promise<void>;
+    append(delta: string): Promise<void>;
+    replace(text: string): Promise<void>;
+    finish(finalText?: string): Promise<void>;
+    private ensureMessage;
+    private scheduleEdit;
+    private startInFlightEdit;
+    private flushEdit;
+    private cancelScheduledEdit;
+    private awaitInFlightEdit;
+    private throwIfAsyncError;
+    private assertOpen;
+}
+export declare function splitTelegramText(text: string, maxChars: number): string[];
+//# sourceMappingURL=message-stream.d.ts.map

package/dist/message-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-stream.d.ts","sourceRoot":"","sources":["../src/message-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,IAAI,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAQhG,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EAEf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB;IAChE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,4BAA4B;IAC3C,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,2BAA2B,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjE,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACnE;AAMD,qBAAa,qBAAsB,YAAW,kBAAkB;IAC9D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiB;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IAEjE,OAAO,CAAC,WAAW,CAAM;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,kBAAkB,CAA2C;IACrE,OAAO,CAAC,SAAS,CAA4C;IAC7D,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,4BAA4B;IAoB3C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQpC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAyBjC,aAAa;IAyB3B,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,iBAAiB;YAYX,SAAS;IASvB,OAAO,CAAC,mBAAmB;YAOb,iBAAiB;YAOjB,iBAAiB;IAY/B,OAAO,CAAC,UAAU;CAKnB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAK1E"}

package/dist/message-stream.js

@@ -0,0 +1,168 @@
+import { DEFAULT_EMPTY_FINAL_TEXT, DEFAULT_MAX_MESSAGE_CHARS, buildStreamingTailPreview, normalizeTrailing, splitTextByCodePoints, } from "@mono-agent/agent-contracts";
+const DEFAULT_INITIAL_STATUS_TEXT = "Thinking…";
+const DEFAULT_EDIT_DEBOUNCE_MS = 750;
+const EMPTY_FINAL_TEXT = DEFAULT_EMPTY_FINAL_TEXT;
+export class TelegramMessageStream {
+    api;
+    chatId;
+    initialStatusText;
+    editDebounceMs;
+    maxMessageChars;
+    replyToMessageId;
+    logger;
+    currentText = "";
+    statusText;
+    sentMessage;
+    sendMessagePromise;
+    editTimer;
+    inFlightEdit;
+    lastAsyncError;
+    finished = false;
+    constructor(options) {
+        this.api = options.api;
+        this.chatId = options.chatId;
+        this.initialStatusText = normalizeTelegramText(options.initialStatusText ?? DEFAULT_INITIAL_STATUS_TEXT);
+        this.statusText = this.initialStatusText;
+        this.editDebounceMs = options.editDebounceMs ?? DEFAULT_EDIT_DEBOUNCE_MS;
+        this.maxMessageChars = options.maxMessageChars ?? DEFAULT_MAX_MESSAGE_CHARS;
+        this.replyToMessageId = options.replyToMessageId;
+        this.logger = options.logger;
+        if (!Number.isInteger(this.maxMessageChars) || this.maxMessageChars < 32) {
+            throw new RangeError("maxMessageChars must be an integer of at least 32.");
+        }
+        if (!Number.isFinite(this.editDebounceMs) || this.editDebounceMs < 0) {
+            throw new RangeError("editDebounceMs must be a non-negative number.");
+        }
+    }
+    async status(text) {
+        this.assertOpen();
+        await this.throwIfAsyncError();
+        this.statusText = normalizeTelegramText(text);
+        const hadMessage = this.sentMessage !== undefined;
+        await this.ensureMessage();
+        if (hadMessage) {
+            await this.flushEdit(this.statusText);
+        }
+    }
+    async append(delta) {
+        this.assertOpen();
+        await this.throwIfAsyncError();
+        if (delta.length === 0) {
+            return;
+        }
+        this.currentText += delta;
+        await this.ensureMessage();
+        this.scheduleEdit();
+    }
+    async replace(text) {
+        this.assertOpen();
+        await this.throwIfAsyncError();
+        this.currentText = text;
+        await this.ensureMessage();
+        this.scheduleEdit();
+    }
+    async finish(finalText) {
+        if (this.finished) {
+            return;
+        }
+        this.finished = true;
+        if (finalText !== undefined) {
+            this.currentText = finalText;
+        }
+        this.cancelScheduledEdit();
+        await this.throwIfAsyncError();
+        await this.awaitInFlightEdit();
+        await this.throwIfAsyncError();
+        const chunks = splitTelegramText(this.currentText, this.maxMessageChars);
+        const [firstChunk, ...remainingChunks] = chunks;
+        await this.ensureMessage();
+        await this.flushEdit(firstChunk ?? EMPTY_FINAL_TEXT);
+        for (const chunk of remainingChunks) {
+            await this.api.sendMessage({ chat_id: this.chatId, text: chunk });
+        }
+    }
+    async ensureMessage() {
+        if (this.sentMessage !== undefined) {
+            return this.sentMessage;
+        }
+        if (this.sendMessagePromise === undefined) {
+            const params = {
+                chat_id: this.chatId,
+                text: this.statusText,
+            };
+            if (this.replyToMessageId !== undefined) {
+                params.reply_to_message_id = this.replyToMessageId;
+            }
+            this.sendMessagePromise = this.api.sendMessage(params);
+        }
+        this.sentMessage = await this.sendMessagePromise;
+        return this.sentMessage;
+    }
+    scheduleEdit() {
+        this.cancelScheduledEdit();
+        if (this.editDebounceMs === 0) {
+            this.startInFlightEdit();
+            return;
+        }
+        this.editTimer = setTimeout(() => {
+            this.editTimer = undefined;
+            this.startInFlightEdit();
+        }, this.editDebounceMs);
+    }
+    startInFlightEdit() {
+        const text = buildStreamingPreview(this.currentText, this.maxMessageChars);
+        this.inFlightEdit = this.flushEdit(text).catch((error) => {
+            this.lastAsyncError = error;
+            this.logger?.error?.("Telegram stream edit failed.", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        });
+        void this.inFlightEdit.catch(() => undefined);
+    }
+    async flushEdit(text) {
+        const message = await this.ensureMessage();
+        await this.api.editMessageText({
+            chat_id: this.chatId,
+            message_id: message.message_id,
+            text: normalizeTelegramText(text),
+        });
+    }
+    cancelScheduledEdit() {
+        if (this.editTimer !== undefined) {
+            clearTimeout(this.editTimer);
+            this.editTimer = undefined;
+        }
+    }
+    async awaitInFlightEdit() {
+        if (this.inFlightEdit !== undefined) {
+            await this.inFlightEdit;
+            this.inFlightEdit = undefined;
+        }
+    }
+    async throwIfAsyncError() {
+        if (this.inFlightEdit !== undefined) {
+            await this.awaitInFlightEdit();
+        }
+        if (this.lastAsyncError !== undefined) {
+            const error = this.lastAsyncError;
+            this.lastAsyncError = undefined;
+            throw error;
+        }
+    }
+    assertOpen() {
+        if (this.finished) {
+            throw new Error("Cannot write to a finished TelegramMessageStream.");
+        }
+    }
+}
+export function splitTelegramText(text, maxChars) {
+    return splitTextByCodePoints(normalizeTrailing(text, EMPTY_FINAL_TEXT), maxChars);
+}
+function buildStreamingPreview(text, maxChars) {
+    return buildStreamingTailPreview(normalizeTrailing(text, EMPTY_FINAL_TEXT), maxChars, "…\n");
+}
+function normalizeTelegramText(text) {
+    return text.trimEnd();
+}
+//# sourceMappingURL=message-stream.js.map

package/dist/message-stream.js.map

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

package/dist/start.d.ts

@@ -0,0 +1,58 @@
+import { type AgentResponder, type TelegramAdapterLogger, type TelegramAdapterMessages, type TelegramAdapterStreamOptions } from "./adapter.js";
+import { type TelegramLongPollerOptions, type TelegramLongPollerStartOptions } from "./long-poller.js";
+import { type TelegramBotApiClientOptions } from "./telegram-client.js";
+import type { TelegramBotApi, TelegramChatId } from "./types.js";
+/**
+ * Minimal surface a long poller must expose for {@link startTelegramAdapter} to
+ * drive it. The real {@link TelegramLongPoller} satisfies this, and tests can
+ * supply a fake via {@link TelegramAdapterStartOptions.pollerFactory}.
+ */
+export interface TelegramPollerLike {
+    start(options?: TelegramLongPollerStartOptions): Promise<void>;
+}
+export interface TelegramAdapterStartOptions {
+    /** Bot API token, used to construct the default {@link TelegramBotApiClient}. */
+    readonly botToken: string;
+    /** Allowlisted chat ids. Required unless {@link allowAllChats} is true. */
+    readonly allowedChatIds?: readonly TelegramChatId[];
+    /** Explicitly permit every chat. Leave off when using an allowlist. */
+    readonly allowAllChats?: boolean;
+    /** Responder the adapter routes authorized text updates to. */
+    readonly responder: AgentResponder;
+    /** Optional per-response stream tuning forwarded to the adapter. */
+    readonly stream?: TelegramAdapterStreamOptions;
+    /** Optional message-copy overrides forwarded to the adapter. */
+    readonly messages?: TelegramAdapterMessages;
+    /** Optional logger shared by the adapter, stream, and poller. */
+    readonly logger?: TelegramAdapterLogger;
+    /** Restrict the update types requested from Telegram. Defaults to messages only. */
+    readonly allowedUpdates?: readonly string[];
+    /** Delete any configured webhook before polling. Defaults to true. */
+    readonly deleteWebhookOnStart?: boolean;
+    /**
+     * Override how the {@link TelegramBotApi} client is built. Defaults to a real
+     * {@link TelegramBotApiClient}. Tests inject a fake to avoid hitting Telegram.
+     */
+    readonly clientFactory?: (options: TelegramBotApiClientOptions) => TelegramBotApi;
+    /**
+     * Override how the long poller is built. Defaults to a real
+     * {@link TelegramLongPoller}. Tests inject a fake to assert wiring and stop.
+     */
+    readonly pollerFactory?: (options: TelegramLongPollerOptions) => TelegramPollerLike;
+}
+export interface TelegramAdapterStartResult {
+    /** Stops the long poller cleanly and waits for the polling loop to settle. */
+    stop(): Promise<void>;
+}
+/**
+ * Composition-root entrypoint: builds the Telegram client, adapter, and long
+ * poller from a single options bag and starts polling. Mirrors the HTTP
+ * adapters' `startX(options): Promise<{ stop }>` shape so a host can launch
+ * Telegram with one call.
+ *
+ * Fail-closed: the underlying {@link TelegramAdapter} throws when neither
+ * {@link TelegramAdapterStartOptions.allowedChatIds} nor
+ * {@link TelegramAdapterStartOptions.allowAllChats} is provided.
+ */
+export declare function startTelegramAdapter(options: TelegramAdapterStartOptions): Promise<TelegramAdapterStartResult>;
+//# sourceMappingURL=start.d.ts.map

package/dist/start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EAClC,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,8BAA8B,EACpC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,OAAO,CAAC,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,2BAA2B;IAC1C,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD,uEAAuE;IACvE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,4BAA4B,CAAC;IAC/C,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IAC5C,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,oFAAoF;IACpF,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,2BAA2B,KAAK,cAAc,CAAC;IAClF;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,kBAAkB,CAAC;CACrF;AAED,MAAM,WAAW,0BAA0B;IACzC,8EAA8E;IAC9E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CA+CrC"}

package/dist/start.js

@@ -0,0 +1,57 @@
+import { TelegramAdapter, } from "./adapter.js";
+import { TelegramLongPoller, } from "./long-poller.js";
+import { TelegramBotApiClient, } from "./telegram-client.js";
+/**
+ * Composition-root entrypoint: builds the Telegram client, adapter, and long
+ * poller from a single options bag and starts polling. Mirrors the HTTP
+ * adapters' `startX(options): Promise<{ stop }>` shape so a host can launch
+ * Telegram with one call.
+ *
+ * Fail-closed: the underlying {@link TelegramAdapter} throws when neither
+ * {@link TelegramAdapterStartOptions.allowedChatIds} nor
+ * {@link TelegramAdapterStartOptions.allowAllChats} is provided.
+ */
+export async function startTelegramAdapter(options) {
+    const buildClient = options.clientFactory ?? ((clientOptions) => new TelegramBotApiClient(clientOptions));
+    const buildPoller = options.pollerFactory ?? ((pollerOptions) => new TelegramLongPoller(pollerOptions));
+    const api = buildClient({ token: options.botToken });
+    const adapter = new TelegramAdapter({
+        api,
+        responder: options.responder,
+        ...(options.allowedChatIds === undefined ? {} : { allowedChatIds: [...options.allowedChatIds] }),
+        ...(options.allowAllChats === undefined ? {} : { allowAllChats: options.allowAllChats }),
+        ...(options.stream === undefined ? {} : { stream: options.stream }),
+        ...(options.messages === undefined ? {} : { messages: options.messages }),
+        ...(options.logger === undefined ? {} : { logger: options.logger }),
+    });
+    const poller = buildPoller({
+        api,
+        adapter,
+        deleteWebhookOnStart: options.deleteWebhookOnStart ?? true,
+        allowedUpdates: options.allowedUpdates === undefined ? ["message"] : [...options.allowedUpdates],
+        ...(options.logger === undefined ? {} : { logger: options.logger }),
+    });
+    const controller = new AbortController();
+    const running = poller.start({ signal: controller.signal });
+    // Surface late polling failures to the shared logger without leaving an
+    // unhandled rejection; stop() still awaits this same promise.
+    running.catch((error) => {
+        if (!controller.signal.aborted) {
+            options.logger?.error?.("Telegram polling stopped with an error.", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+    let stopped = false;
+    return {
+        async stop() {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            controller.abort();
+            await running.catch(() => undefined);
+        },
+    };
+}
+//# sourceMappingURL=start.js.map

package/dist/start.js.map

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

package/dist/telegram-client.d.ts

@@ -0,0 +1,38 @@
+import type { TelegramBotApi, TelegramDeleteWebhookParams, TelegramEditMessageTextParams, TelegramGetUpdatesParams, TelegramRequestOptions, TelegramSendMessageParams, TelegramSentMessage, TelegramUpdate } from "./types.js";
+export type TelegramApiErrorKind = "http" | "telegram" | "malformed" | "network" | "aborted";
+export interface TelegramApiErrorDetails {
+    kind: TelegramApiErrorKind;
+    method: string;
+    status?: number;
+    errorCode?: number;
+    telegramDescription?: string;
+    cause?: unknown;
+}
+export declare class TelegramApiError extends Error {
+    readonly kind: TelegramApiErrorKind;
+    readonly method: string;
+    readonly status?: number;
+    readonly errorCode?: number;
+    readonly telegramDescription?: string;
+    readonly cause?: unknown;
+    constructor(message: string, details: TelegramApiErrorDetails);
+}
+export interface TelegramBotApiClientOptions {
+    token: string;
+    apiBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    requestTimeoutMs?: number;
+}
+export declare class TelegramBotApiClient implements TelegramBotApi {
+    private readonly token;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    private readonly requestTimeoutMs;
+    constructor(options: TelegramBotApiClientOptions);
+    sendMessage(params: TelegramSendMessageParams, options?: TelegramRequestOptions): Promise<TelegramSentMessage>;
+    editMessageText(params: TelegramEditMessageTextParams, options?: TelegramRequestOptions): Promise<TelegramSentMessage | true>;
+    getUpdates(params: TelegramGetUpdatesParams, options?: TelegramRequestOptions): Promise<TelegramUpdate[]>;
+    deleteWebhook(params?: TelegramDeleteWebhookParams, options?: TelegramRequestOptions): Promise<true>;
+    private request;
+}
+//# sourceMappingURL=telegram-client.d.ts.map

package/dist/telegram-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram-client.d.ts","sourceRoot":"","sources":["../src/telegram-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,2BAA2B,EAC3B,6BAA6B,EAC7B,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,oBAAoB,GAC5B,MAAM,GACN,UAAU,GACV,WAAW,GACX,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB;CAkB9D;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkBD,qBAAa,oBAAqB,YAAW,cAAc;IACzD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAE9B,OAAO,EAAE,2BAA2B;IAsBhD,WAAW,CACT,MAAM,EAAE,yBAAyB,EACjC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,mBAAmB,CAAC;IAI/B,eAAe,CACb,MAAM,EAAE,6BAA6B,EACrC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAQtC,UAAU,CACR,MAAM,EAAE,wBAAwB,EAChC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,cAAc,EAAE,CAAC;IAI5B,aAAa,CACX,MAAM,GAAE,2BAAgC,EACxC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC;YAIF,OAAO;CAiFtB"}