@xbibzlibrary/telebibz 0.1.19 → 0.3.1

package/dist-cjs/src/core/bot.js

@@ -12,6 +12,8 @@ const plugin_js_1 = require("../plugins/plugin.js");
 const logger_js_1 = require("../observability/logger.js");
 const terminal_js_1 = require("../branding/terminal.js");
 const conversation_js_1 = require("../state/conversation.js");
+const broadcast_js_1 = require("../broadcast/broadcast.js");
+const concurrency_js_1 = require("../utils/concurrency.js");
 class Bot {
     api;
     router;
@@ -27,36 +29,56 @@ class Bot {
     pollingAbort;
     offset = 0;
     me;
+    /** Caps how many updates run at once (default: unlimited). */
+    updateLimiter;
+    /** Per-chat processing chains: parallel across chats, ordered within a chat. */
+    chatChains = new Map();
+    /** Memoized init so a burst of updates triggers exactly one getMe call. */
+    initOnce;
+    brandingEnabled;
+    /** Branding effects run only on an interactive TTY; structured logs stay untouched otherwise. */
+    brandingActive;
+    activeBanner;
+    errorHandler;
     constructor(options) {
         const config = typeof options === "string" ? { token: options } : options;
         if (!config.token || !/^\d+:[\w-]+$/.test(config.token))
             throw new Error("A valid Telegram bot token is required.");
         this.token = config.token;
-        (0, terminal_js_1.printTerminalBranding)();
+        this.brandingEnabled = config.branding ?? true;
+        this.brandingActive = this.brandingEnabled && process.stdout.isTTY === true;
         this.logger = config.logger instanceof logger_js_1.Logger ? config.logger : (0, logger_js_1.createLogger)(config.logger);
         this.router = new router_js_1.Router(config.router);
         this.session = config.session ?? new storage_js_1.MemoryStorage();
         this.services = { ...(config.services ?? {}) };
         const transport = config.transport ?? new transport_js_1.FetchTransport({ baseUrl: `${config.apiBaseUrl ?? "https://api.telegram.org"}/bot${config.token}`, ...(config.transportOptions ?? {}) });
         this.api = new client_js_1.ApiClient({
-            transport,
             hooks: {
                 onRequest: (context) => { this.logger.trace("api.request", { method: context.method, payload: context.payload }); return this.events.emit("api:request", { method: context.method, payload: context.payload }); },
                 onResponse: (context) => { this.logger.debug("api.response", { method: context.method, durationMs: context.durationMs ?? 0, ok: context.response?.ok }); return this.events.emit("api:response", { method: context.method, durationMs: context.durationMs ?? 0, response: context.response }); },
                 onError: (context) => { this.logger.error("api.error", { method: context.method, durationMs: context.durationMs ?? 0, error: context.error }); return this.events.emit("api:error", { method: context.method, durationMs: context.durationMs ?? 0, error: context.error }); },
             },
+            transport,
         });
         this.plugins = new plugin_js_1.PluginManager(this);
+        this.updateLimiter = new concurrency_js_1.Limiter(config.updates?.concurrency ?? Infinity);
         this.pollingOptions = {
-            timeout: config.polling?.timeout ?? 30,
-            limit: config.polling?.limit ?? 100,
             allowedUpdates: config.polling?.allowedUpdates ?? [],
-            retryDelayMs: config.polling?.retryDelayMs ?? 500,
+            limit: config.polling?.limit ?? 100,
             maxRetryDelayMs: config.polling?.maxRetryDelayMs ?? 30_000,
+            retryDelayMs: config.polling?.retryDelayMs ?? 500,
+            timeout: config.polling?.timeout ?? 30,
         };
-        this.logger.info("bot.created", { status: this.statusValue });
+        this.startupLog("bot.created", { status: this.statusValue });
         void this.events.emit("bot:created", { bot: this });
     }
+    /** Startup info logs are demoted to debug while the branding sequence owns the terminal. */
+    startupLog(event, context) {
+        if (this.brandingActive)
+            this.logger.debug(event, context);
+        else
+            this.logger.info(event, context);
+    }
     get status() { return this.statusValue; }
     get botInfo() { return this.me; }
     use(...middleware) { this.middlewares.push(...middleware); return this; }
@@ -64,6 +86,21 @@ class Bot {
     callback(pattern, handler) { this.router.callback(pattern, handler); return this; }
     onText(text, handler) { this.router.text(text, handler); return this; }
     onRegex(expression, handler) { this.router.regex(expression, handler); return this; }
+    /** Registers a handler for update types: `bot.on("message:photo", handler)` or `bot.on(["message:text", "callback_query:data"], handler)`. */
+    on(filter, handler) { this.router.on(filter, handler); return this; }
+    /** Registers a handler for exact text or a regular expression, mirroring familiar frameworks. */
+    hears(trigger, handler) {
+        if (trigger instanceof RegExp)
+            this.router.regex(trigger, handler);
+        else
+            this.router.text(trigger, handler);
+        return this;
+    }
+    /**
+     * Sets the error boundary for update handlers. When set, handler failures are
+     * passed here instead of rejecting `handleUpdate()` (webhooks answer 200).
+     */
+    catch(handler) { this.errorHandler = handler; return this; }
     usePlugin(plugin) { this.plugins.use(plugin); return this; }
     /**
      * Routes subsequent messages to the active Wizard step for the same chat/user.
@@ -92,20 +129,29 @@ class Bot {
     async init() {
         if (this.statusValue === "initialized" || this.statusValue === "running")
             return this;
-        this.logger.info("bot.initializing");
-        const animation = (0, terminal_js_1.startTerminalAnimation)("Connecting to Telegram and initializing bot");
+        this.startupLog("bot.initializing", {});
+        const standaloneBanner = this.brandingActive && !this.activeBanner;
+        const animation = this.brandingActive ? undefined : (0, terminal_js_1.startTerminalAnimation)("Connecting to Telegram and initializing bot");
+        if (standaloneBanner)
+            (0, terminal_js_1.printTeleBibzBanner)({ subtitle: "Connecting to Telegram..." });
         try {
             this.me = await this.api.methods.getMe();
             this.statusValue = "initialized";
-            this.logger.info("bot.initialized", { botId: this.me.id, username: this.me.username });
+            this.startupLog("bot.initialized", { botId: this.me.id, username: this.me.username });
             await this.events.emit("bot:initialized", { bot: this });
             await this.plugins.setup();
             await this.plugins.start();
-            animation.stop("Bot initialized; ready to start");
+            if (standaloneBanner)
+                (0, terminal_js_1.printStatusLine)(`✓ Bot initialized as @${this.me.username ?? this.me.id}`);
+            else
+                animation?.stop("Bot initialized; ready to start");
             return this;
         }
         catch (error) {
-            animation.stop("Error: bot could not initialize");
+            if (standaloneBanner)
+                (0, terminal_js_1.printStatusLine)(`✗ Bot could not initialize: ${error instanceof Error ? error.message : String(error)}`);
+            else
+                animation?.stop("Error: bot could not initialize");
             throw error;
         }
     }
@@ -113,15 +159,35 @@ class Bot {
     async launch(options = { mode: "polling" }) {
         if (options.mode !== "polling")
             throw new Error("Use createWebhookHandler() for webhook mode.");
-        await this.init();
+        const runBrandingSequence = this.brandingActive && !this.activeBanner && (this.statusValue === "created" || this.statusValue === "stopped");
+        if (runBrandingSequence) {
+            await (0, terminal_js_1.runStartupSequence)();
+            this.activeBanner = (0, terminal_js_1.startTeleBibzBanner)({ subtitle: "Connecting to Telegram..." });
+        }
+        try {
+            await this.init();
+        }
+        catch (error) {
+            if (this.activeBanner) {
+                this.activeBanner.stop(`Connection failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                this.activeBanner = undefined;
+            }
+            throw error;
+        }
+        if (this.activeBanner) {
+            this.activeBanner.stop(`Connected as @${this.me?.username ?? this.me?.id}`);
+            this.activeBanner = undefined;
+        }
         if (this.statusValue === "running")
             return;
         this.statusValue = "starting";
-        this.logger.info("bot.starting", { mode: options.mode });
+        this.startupLog("bot.starting", { mode: options.mode });
         await this.events.emit("bot:starting", { bot: this });
         this.pollingAbort = new AbortController();
         this.statusValue = "running";
         await this.events.emit("bot:started", { bot: this });
+        if (this.brandingActive)
+            (0, terminal_js_1.printStatusLine)("Listening for updates...");
         await this.poll(options.timeout ?? this.pollingOptions.timeout, options.allowedUpdates ?? this.pollingOptions.allowedUpdates, this.pollingAbort.signal);
     }
     async stop() {
@@ -134,7 +200,10 @@ class Bot {
         await this.plugins.stop();
         await this.plugins.dispose();
         this.statusValue = "stopped";
-        this.logger.info("bot.stopped");
+        if (this.brandingActive)
+            (0, terminal_js_1.printStatusLine)("Bot stopped.");
+        else
+            this.logger.info("bot.stopped");
         await this.events.emit("bot:stopped", { bot: this });
     }
     async restart() { await this.stop(); await this.start(); }
@@ -150,8 +219,69 @@ class Bot {
     async getMe() { const me = await this.api.methods.getMe(); this.me = me; return me; }
     async setCommands(commands, scope, languageCode) { return this.api.call("setMyCommands", { commands, scope, language_code: languageCode }); }
     async deleteCommands(scope, languageCode) { return this.api.call("deleteMyCommands", { scope, language_code: languageCode }); }
+    /**
+     * Handles a single update. Updates for different chats run in parallel;
+     * updates for the same chat are processed strictly in arrival order so
+     * sessions, wizards, and conversations never interleave. Rejects for this
+     * update's failure (as before) without affecting other updates.
+     */
     async handleUpdate(update) {
-        this.logger.debug("update.received", { update: (0, logger_js_1.summarizeUpdate)(update, this.logger.includeUpdateContent) });
+        const key = this.conversationKey(update);
+        const previous = this.chatChains.get(key);
+        const run = (previous ?? Promise.resolve()).catch(() => undefined).then(() => this.processUpdate(update));
+        const tail = run.then(() => undefined, () => undefined);
+        this.chatChains.set(key, tail);
+        void tail.then(() => {
+            if (this.chatChains.get(key) === tail)
+                this.chatChains.delete(key);
+        });
+        await run;
+    }
+    /**
+     * Handles a whole batch of updates at once: every chat in the batch is
+     * processed immediately (parallel across chats, ordered per chat), so a
+     * burst of 1000 messages is not stuck behind one slow handler. Individual
+     * handler failures are logged, emitted as `update:error`, and passed to the
+     * `catch()` error boundary; they never reject this promise.
+     */
+    async handleUpdates(updates) {
+        await Promise.all(updates.map(async (update) => {
+            try {
+                await this.handleUpdate(update);
+            }
+            catch {
+                // Already logged and emitted by processUpdate; the polling loop must
+                // keep flowing no matter how many handlers failed.
+            }
+        }));
+    }
+    /**
+     * Sends to many chats in parallel — built for broadcasts to 1000+ users.
+     * There is no proactive cooldown: every chat is attempted at once (up to
+     * `concurrency`). When Telegram answers 429, the send is retried
+     * automatically after exactly the `retry_after` delay Telegram ordered, so
+     * bursts deliver completely instead of failing.
+     */
+    async broadcast(chatIds, send, options) {
+        return (0, broadcast_js_1.runBroadcast)(chatIds, send, options);
+    }
+    /** Runs init() once even when many updates arrive concurrently. */
+    ensureInitialized() {
+        if (this.me)
+            return Promise.resolve();
+        if (!this.initOnce) {
+            this.initOnce = this.init().then(() => { this.initOnce = undefined; }, (error) => {
+                this.initOnce = undefined;
+                throw error;
+            });
+        }
+        return this.initOnce;
+    }
+    async processUpdate(update) {
+        await this.updateLimiter.run(() => this.runUpdate(update));
+    }
+    async runUpdate(update) {
+        this.logger.incoming((0, logger_js_1.describeIncomingUpdate)(update));
         const message = update.message
             ?? update.edited_message
             ?? update.channel_post
@@ -163,10 +293,10 @@ class Bot {
         const key = this.conversationKey(update);
         const session = await this.session.get(key) ?? {};
         if (!this.me)
-            await this.init();
+            await this.ensureInitialized();
         if (!this.me)
             return;
-        const ctx = new context_js_1.Context({ update, api: this.api, session, services: this.services });
+        const ctx = new context_js_1.Context({ update, api: this.api, session, services: this.services, me: this.me });
         await this.events.emit("update", { update });
         if (message) {
             await this.events.emit("message", { message });
@@ -189,22 +319,42 @@ class Bot {
             this.logger.error("update.handler_error", { update: (0, logger_js_1.summarizeUpdate)(update, this.logger.includeUpdateContent), error });
             await this.events.emit("update:error", { update, error });
             await this.events.emit("bot:error", { bot: this, error });
+            if (this.errorHandler) {
+                // With an error boundary registered, the failure is considered handled:
+                // webhooks answer 200 and polling continues without rethrowing.
+                await this.errorHandler(error, ctx);
+                return;
+            }
             throw error;
         }
     }
     conversationKey(update) {
+        if (update.callback_query) {
+            const chat = update.callback_query.message?.chat;
+            const userId = update.callback_query.from.id;
+            if (chat?.id !== undefined)
+                return `${chat.id}:${userId}`;
+            return `user:${userId}`;
+        }
+        if (update.inline_query?.from?.id !== undefined)
+            return `user:${update.inline_query.from.id}`;
+        if (update.chosen_inline_result?.from?.id !== undefined)
+            return `user:${update.chosen_inline_result.from.id}`;
         const message = update.message
             ?? update.edited_message
             ?? update.channel_post
             ?? update.edited_channel_post
             ?? update.business_message
             ?? update.edited_business_message
-            ?? update.guest_message
-            ?? update.callback_query?.message;
+            ?? update.guest_message;
         if (message?.chat?.id !== undefined)
             return `${message.chat.id}:${message.from?.id ?? "anonymous"}`;
-        if (update.callback_query?.from?.id !== undefined)
-            return `user:${update.callback_query.from.id}`;
+        if (update.chat_member?.chat?.id !== undefined)
+            return `${update.chat_member.chat.id}:${update.chat_member.from.id}`;
+        if (update.my_chat_member?.chat?.id !== undefined)
+            return `${update.my_chat_member.chat.id}:${update.my_chat_member.from.id}`;
+        if (update.chat_join_request?.chat?.id !== undefined)
+            return `${update.chat_join_request.chat.id}:${update.chat_join_request.from.id}`;
         return `update:${update.update_id}`;
     }
     async waitForRetry(delayMs, signal) {
@@ -225,20 +375,19 @@ class Bot {
     }
     async poll(timeout, allowedUpdates, signal) {
         let delay = this.pollingOptions.retryDelayMs;
+        // Telegram holds a long-poll connection open for `timeout` seconds, so the
+        // request timeout must exceed it to avoid aborting a healthy connection.
+        const requestTimeoutMs = timeout * 1_000 + 10_000;
         while (!signal.aborted) {
             try {
-                const updates = await this.api.methods.getUpdates({ offset: this.offset, limit: this.pollingOptions.limit, timeout, allowed_updates: allowedUpdates });
+                const updates = await this.api.request("getUpdates", { offset: this.offset, limit: this.pollingOptions.limit, timeout, allowed_updates: allowedUpdates }, signal, { timeoutMs: requestTimeoutMs });
                 delay = this.pollingOptions.retryDelayMs;
+                // Confirm the whole batch first, then process it: updates run in
+                // parallel across chats (ordered per chat) instead of one by one.
                 for (const update of updates) {
                     this.offset = Math.max(this.offset, update.update_id + 1);
-                    try {
-                        await this.handleUpdate(update);
-                    }
-                    catch {
-                        // The update has already advanced the offset. Continue with the rest of
-                        // the batch instead of reconnecting or replaying a failed handler.
-                    }
                 }
+                await this.handleUpdates(updates);
             }
             catch (error) {
                 if (signal.aborted)

package/dist-cjs/src/index.js

@@ -28,6 +28,8 @@ __exportStar(require("./queue/queue.js"), exports);
 __exportStar(require("./plugins/plugin.js"), exports);
 __exportStar(require("./webhook/handler.js"), exports);
 __exportStar(require("./utils/text.js"), exports);
+__exportStar(require("./utils/concurrency.js"), exports);
+__exportStar(require("./broadcast/broadcast.js"), exports);
 __exportStar(require("./state/conversation.js"), exports);
 __exportStar(require("./state/forms.js"), exports);
 __exportStar(require("./state/menu.js"), exports);

package/dist-cjs/src/keyboard/index.js

@@ -11,6 +11,10 @@ class InlineKeyboard {
     webApp(text, url) { return this.button({ text, web_app: { url } }); }
     pay(text = "Pay") { return this.button({ text, pay: true }); }
     copy(text, copiedText) { return this.button({ text, copy_text: { text: copiedText } }); }
+    switchInline(text, query = "") { return this.button({ text, switch_inline_query: query }); }
+    switchInlineCurrent(text, query = "") { return this.button({ text, switch_inline_query_current_chat: query }); }
+    login(text, url, options = {}) { return this.button({ text, login_url: { url, ...options } }); }
+    game(text) { return this.button({ text, callback_game: {} }); }
     button(button) { this.ensureRow().push(validateInlineButton(button)); return this; }
     row(...buttons) { this.rows.push(buttons.map(validateInlineButton)); return this; }
     conditional(condition, factory) { return condition ? factory(this) : this; }
@@ -25,17 +29,25 @@ class InlineKeyboard {
 exports.InlineKeyboard = InlineKeyboard;
 class ReplyKeyboard {
     rows = [];
+    options = {};
     text(text) { return this.button({ text }); }
     contact(text) { return this.button({ text, request_contact: true }); }
     location(text) { return this.button({ text, request_location: true }); }
     poll(text, type) { return this.button({ text, request_poll: type ? { type } : {} }); }
     webApp(text, url) { return this.button({ text, web_app: { url } }); }
+    requestUsers(text, options = {}) { return this.button({ text, request_users: options }); }
+    requestChat(text, options = {}) { return this.button({ text, request_chat: options }); }
+    resized(resize = true) { this.options.resize_keyboard = resize; return this; }
+    oneTime(oneTime = true) { this.options.one_time_keyboard = oneTime; return this; }
+    persistent(persistent = true) { this.options.is_persistent = persistent; return this; }
+    placeholder(text) { this.options.input_field_placeholder = text; return this; }
+    selective(selective = true) { this.options.selective = selective; return this; }
     button(button) { this.ensureRow().push(button); return this; }
     row(...buttons) { this.rows.push([...buttons]); return this; }
     grid(buttons, columns) { if (!Number.isInteger(columns) || columns < 1)
         throw new RangeError("columns must be a positive integer"); for (let index = 0; index < buttons.length; index += columns)
         this.rows.push(buttons.slice(index, index + columns)); return this; }
-    build(options = {}) { return { keyboard: this.rows.map((row) => [...row]), ...options }; }
+    build(options = {}) { return { keyboard: this.rows.map((row) => [...row]), ...this.options, ...options }; }
     asReplyMarkup() { return this.build(); }
     ensureRow() { const row = this.rows.at(-1); if (row)
         return row; const next = []; this.rows.push(next); return next; }

package/dist-cjs/src/observability/logger.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = void 0;
+exports.Logger = exports.INCOMING_TEXT_LIMIT = void 0;
 exports.redact = redact;
+exports.formatLocalStamp = formatLocalStamp;
+exports.describeIncomingUpdate = describeIncomingUpdate;
 exports.summarizeUpdate = summarizeUpdate;
 exports.createLogger = createLogger;
 const priorities = { silent: 99, error: 0, warn: 1, info: 2, debug: 3, trace: 4 };
@@ -88,6 +90,84 @@ function updateType(update) {
         return "poll_answer";
     return "unknown";
 }
+exports.INCOMING_TEXT_LIMIT = 50;
+function padNumber(value) { return String(value).padStart(2, "0"); }
+/** Formats a date as `dd/mm/yyyy hh:mm:ss` in local time. */
+function formatLocalStamp(date = new Date()) {
+    return `${padNumber(date.getDate())}/${padNumber(date.getMonth() + 1)}/${date.getFullYear()} ${padNumber(date.getHours())}:${padNumber(date.getMinutes())}:${padNumber(date.getSeconds())}`;
+}
+function truncateForDisplay(value, limit = exports.INCOMING_TEXT_LIMIT) {
+    if (value.length <= limit)
+        return { text: value, truncated: false };
+    return { text: `${value.slice(0, limit)}…`, truncated: true };
+}
+function nicknameFromUser(user) {
+    if (!user)
+        return undefined;
+    const name = [user.first_name, user.last_name].filter(Boolean).join(" ").trim();
+    return name.length > 0 ? name : user.username ?? String(user.id);
+}
+function messageMediaType(message) {
+    for (const key of ["photo", "video", "video_note", "animation", "document", "audio", "voice", "sticker", "location", "venue", "contact", "dice", "poll", "story", "paid_media"]) {
+        if (message[key] !== undefined)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * Builds the human-readable description of an incoming update used for the
+ * `[ => ] Message From ...` terminal lines. Text messages and commands are
+ * truncated to 50 characters; callback button data is shown in full.
+ */
+function describeIncomingUpdate(update) {
+    const callback = update.callback_query;
+    if (callback) {
+        const result = { kind: "Callback", fromId: callback.from.id, nickname: nicknameFromUser(callback.from), contentLabel: "Data", content: callback.data };
+        return result;
+    }
+    const message = (update.message ?? update.edited_message ?? update.channel_post ?? update.edited_channel_post ?? update.business_message ?? update.edited_business_message ?? update.guest_message ?? update.edited_guest_message);
+    if (message) {
+        const from = message.from;
+        const nickname = nicknameFromUser(from) ?? (message.chat.title !== undefined ? String(message.chat.title) : message.chat.id !== undefined ? String(message.chat.id) : undefined);
+        const input = { kind: "Message", fromId: from?.id ?? message.chat.id, nickname };
+        const text = message.text;
+        if (text !== undefined) {
+            const truncated = truncateForDisplay(text);
+            input.contentLabel = "Text";
+            input.content = truncated.text;
+            input.truncated = truncated.truncated;
+        }
+        else if (message.caption !== undefined) {
+            const truncated = truncateForDisplay(message.caption);
+            input.contentLabel = "Caption";
+            input.content = truncated.text;
+            input.truncated = truncated.truncated;
+        }
+        else {
+            const media = messageMediaType(message);
+            if (media !== undefined)
+                input.contentLabel = media === "photo" ? "Photo" : media.replace(/_/g, " ").replace(/^./, (character) => character.toUpperCase());
+        }
+        return input;
+    }
+    const inline = update.inline_query;
+    if (inline) {
+        const truncated = truncateForDisplay(inline.query);
+        return { kind: "Inline Query", fromId: inline.from.id, nickname: nicknameFromUser(inline.from), contentLabel: "Query", content: truncated.text, truncated: truncated.truncated };
+    }
+    const chosen = update.chosen_inline_result;
+    if (chosen)
+        return { kind: "Inline Result", fromId: chosen.from.id, nickname: nicknameFromUser(chosen.from), contentLabel: "Result", content: chosen.result_id };
+    const chatScoped = update.chat_member ?? update.my_chat_member ?? update.chat_join_request;
+    if (chatScoped) {
+        return { kind: "Update", fromId: chatScoped.from.id, nickname: nicknameFromUser(chatScoped.from), contentLabel: "Chat", content: chatScoped.chat.title ?? String(chatScoped.chat.id) };
+    }
+    const reaction = update.message_reaction;
+    const reactor = nicknameFromUser(reaction?.from);
+    if (reactor)
+        return { kind: "Reaction", fromId: reaction?.from?.id, nickname: reactor };
+    return { kind: "Update", context: { type: updateType(update) } };
+}
 function summarizeUpdate(update, includeContent = false) {
     const callback = update.callback_query;
     const message = (update.message ?? update.edited_message ?? update.channel_post ?? update.edited_channel_post ?? update.business_message ?? update.edited_business_message ?? update.guest_message ?? update.edited_guest_message ?? callback?.message);
@@ -134,6 +214,10 @@ function createDefaultSink(options, redactKeys) {
     const color = options.color ?? Boolean(stream.isTTY && !process.env.NO_COLOR);
     const format = options.format ?? "pretty";
     return (entry) => {
+        if (typeof entry.text === "string") {
+            stream.write(`${redactString(entry.text)}\n`);
+            return;
+        }
         const safeEntry = redact(entry, redactKeys);
         const line = formatEntry(safeEntry, color, format);
         stream.write(`${line}\n`);
@@ -163,6 +247,34 @@ class Logger {
     info(event, context) { this.write("info", event, context); }
     warn(event, context) { this.write("warn", event, context); }
     error(event, context) { this.write("error", event, context); }
+    /**
+     * Logs an incoming update as the human-readable terminal line:
+     * `[ => ] Message From {id} {nickname} {dd/mm/yyyy} {hh:mm:ss}` followed by
+     * an indented content line. In `json` format it emits a structured entry
+     * with the event name `update.received`.
+     */
+    incoming(input) {
+        if (priorities.info > priorities[this.level])
+            return;
+        if (this.format === "json") {
+            const context = { kind: input.kind, ...(input.fromId !== undefined ? { fromId: input.fromId } : {}), ...(input.nickname !== undefined ? { nickname: input.nickname } : {}), ...(input.content !== undefined ? { content: input.content } : {}), ...(input.truncated ? { truncated: true } : {}), ...input.context };
+            this.write("info", "update.received", context);
+            return;
+        }
+        const stamp = formatLocalStamp();
+        const identity = [input.fromId !== undefined ? String(input.fromId) : undefined, input.nickname].filter(Boolean).join(" ");
+        const arrow = this.color ? `\u001b[36m\u001b[1m[ => ]\u001b[0m` : "[ => ]";
+        const kind = this.color ? `\u001b[1m${input.kind}\u001b[0m` : input.kind;
+        const header = `${arrow} ${kind} From ${identity} ${this.color ? `\u001b[2m${stamp}\u001b[0m` : stamp}`;
+        const lines = [redactString(header)];
+        if (input.content !== undefined || input.contentLabel !== undefined) {
+            const label = input.contentLabel ?? "Content";
+            const value = input.content ?? "";
+            const contentLine = `        ↳ ${label}: ${value}`;
+            lines.push(this.color ? `\u001b[2m${redactString(contentLine)}\u001b[0m` : redactString(contentLine));
+        }
+        this.sink({ timestamp: new Date().toISOString(), level: "info", event: "update.received", text: lines.join("\n") });
+    }
     write(level, event, context = {}) {
         if (priorities[level] > priorities[this.level])
             return;

package/dist-cjs/src/plugins/plugin.js

@@ -13,6 +13,7 @@ exports.ServiceContainer = ServiceContainer;
 class PluginManager {
     plugins = [];
     api;
+    setupComplete = false;
     constructor(bot) {
         const host = bot;
         this.api = {
@@ -39,10 +40,16 @@ class PluginManager {
     }
     use(plugin) { if (this.plugins.some((existing) => existing.name === plugin.name))
         throw new Error(`Plugin already registered: ${plugin.name}`); this.plugins.push(plugin); return this; }
-    async setup() { for (const plugin of this.plugins) {
-        await plugin.install?.(this.api);
-        await plugin.setup?.(this.api);
-    } }
+    /** Installs plugins once; re-running setup after a restart must not double-register middleware. */
+    async setup() {
+        if (this.setupComplete)
+            return;
+        for (const plugin of this.plugins) {
+            await plugin.install?.(this.api);
+            await plugin.setup?.(this.api);
+        }
+        this.setupComplete = true;
+    }
     async start() { for (const plugin of this.plugins)
         await plugin.onStart?.(this.api); }
     async update(context) { for (const plugin of this.plugins)