@coffer-org/plugin-telegram 1.3.2 → 1.4.0

package/dist/runtime/bot.d.ts

@@ -1,4 +1,5 @@
 import type { LoadOpts } from './config.ts';
+export declare function stripHtml(s: string): string;
 export type StartOpts = LoadOpts;
 export declare function startBot(opts?: StartOpts): Promise<boolean>;
 export declare function stopBot(): Promise<void>;

package/dist/runtime/bot.js

@@ -1,13 +1,44 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { TelegramClient, Api } from 'telegram';
-import { LogLevel } from 'telegram/extensions/Logger.js';
-import { StringSession } from 'telegram/sessions/index.js';
-import { NewMessage } from 'telegram/events/index.js';
-import { handleIncoming } from '@coffer-org/plugin-orchestrator/runtime';
+import { TelegramClient, Api } from 'teleproto';
+import { LogLevel } from 'teleproto/extensions/Logger.js';
+import { StringSession } from 'teleproto/sessions/index.js';
+import { NewMessage } from 'teleproto/events/index.js';
+import { handleIncoming, loadGatePolicy } from '@coffer-org/plugin-orchestrator/runtime';
+import { recordUser, recordAssistant, buildChain } from "./chain-store.js";
 import { loadBotConfig, hasCredentials } from "./config.js";
 import { getLogger } from '@coffer-org/sdk/logger';
 const log = getLogger('telegram');
+const FALLBACK_REPLY_WINDOW_MS = 1_800_000;
+const lastByChat = new Map();
+async function replyWindowMs() {
+    try {
+        return (await loadGatePolicy()).replyWindow * 1000;
+    }
+    catch (err) {
+        log.warn(`gate policy load: ${err instanceof Error ? err.message : String(err)} — using default reply window`);
+        return FALLBACK_REPLY_WINDOW_MS;
+    }
+}
+export function stripHtml(s) {
+    return s
+        .replace(/<[^>]*>/g, '')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+const TELEGRAM_FORMAT = [
+    'CRITICAL OUTPUT FORMAT — Telegram HTML ONLY. Format the reply strictly with Telegram\'s HTML subset (<b>, <i>, <code>, <a>, …) and NOTHING else. NEVER use Markdown — no *bold*, _italic_, **bold**, `code`, ```blocks```, # headings, - bullets, or | tables. Markdown does not render here; it shows up as literal characters and breaks the message. When in doubt, use an HTML tag or plain text.',
+    'Inline styling (tags may nest): <b>bold</b>, <i>italic</i>, <u>underline</u>, <s>strike</s>, <code>inline code</code>, <spoiler>spoiler</spoiler>. Links: <a href="https://…">text</a> (also <a href="tg://user?id=123">mention</a>).',
+    'Blocks: <pre>code block</pre> or, for syntax highlight, <pre><code class="language-python">…</code></pre>. Quotes: <blockquote>quote</blockquote>, or <blockquote expandable>long collapsible quote</blockquote>. Bullet lists: start plain lines with "• ".',
+    'Only those tags are parsed. NOT supported here (do not use): <tg-spoiler>, <span>, <ins>, <strike>, <tg-time> — use <spoiler>, <u>, <s> instead. Avoid <tg-emoji> (needs a custom-emoji id + Premium); use ordinary emoji.',
+    'DO NOT use markdown (*, _, #, ```), tables, or images. Escape literal <, >, and & in prose as &lt;, &gt;, and &amp; so they are not read as tags.',
+    'Render any TABLE as a <pre> block with space-aligned columns — real tables are unsupported.',
+    'Beyond the tags, use Unicode symbols and emoji to structure and enrich replies — they render everywhere: bullets (•, ▪, –), separators (─────), arrows (→), status marks (✅ ⚠️ ❌ ⏳), and topic emoji (📅 💰 🏥 🛒 🌱 …). They make messages scannable and friendly.',
+    'Keep replies short and skimmable (messages cap at 4096 chars): prefer short paragraphs and "• " bullet lists over long prose.',
+].join('\n');
 function loadSessionString(file) {
     try {
         return fs.readFileSync(file, 'utf-8');
@@ -46,36 +77,62 @@ export async function startBot(opts = {}) {
     const me = (await tg.getMe());
     const meId = me?.id?.toString();
     log.info(`connected as @${me?.username || me?.firstName || meId}`);
-    async function sendMd(peer, text) {
+    async function sendHtml(peer, text, replyTo) {
         try {
-            return await tg.sendMessage(peer, { message: text, parseMode: 'md' });
+            return await tg.sendMessage(peer, { message: text, parseMode: 'html', replyTo });
         }
         catch {
             try {
-                return await tg.sendMessage(peer, { message: text });
+                return await tg.sendMessage(peer, { message: stripHtml(text), replyTo });
             }
             catch {
                 return undefined;
             }
         }
     }
-    async function editMd(peer, msgId, text) {
+    async function editHtml(peer, msgId, text) {
         try {
-            await tg.editMessage(peer, { message: msgId, text, parseMode: 'md' });
+            await tg.editMessage(peer, { message: msgId, text, parseMode: 'html' });
         }
         catch {
             try {
-                await tg.editMessage(peer, { message: msgId, text });
+                await tg.editMessage(peer, { message: msgId, text: stripHtml(text) });
             }
             catch {
             }
         }
     }
     function startTypingPeer(peer) {
-        const ping = () => tg.invoke(new Api.messages.SetTyping({ peer, action: new Api.SendMessageTypingAction() })).catch(() => { });
-        void ping();
-        const timer = setInterval(() => void ping(), 5000);
-        return () => clearInterval(timer);
+        let logged = false;
+        let stopped = false;
+        let timer;
+        const warn = (err) => {
+            if (logged)
+                return;
+            logged = true;
+            log.warn(`typing indicator: ${err instanceof Error ? err.message : String(err)}`);
+        };
+        void (async () => {
+            let input;
+            try {
+                input = await tg.getInputEntity(peer);
+            }
+            catch (err) {
+                warn(err);
+                return;
+            }
+            if (stopped)
+                return;
+            const ping = () => tg
+                .invoke(new Api.messages.SetTyping({ peer: input, action: new Api.SendMessageTypingAction() }))
+                .catch(warn);
+            void ping();
+            timer = setInterval(() => void ping(), 5000);
+        })();
+        return () => {
+            stopped = true;
+            clearInterval(timer);
+        };
     }
     tg.addEventHandler(async (event) => {
         try {
@@ -100,31 +157,78 @@ export async function startBot(opts = {}) {
             catch {
             }
             log.info(`msg [${chatLabel}]: ${text.slice(0, 80)}`);
-            const chatId = String(event.chatId ?? '?');
-            const userId = message.senderId?.toString() ?? '?';
-            const replyTo = message.replyTo?.replyToMsgId ?? null;
-            const connector = {
-                id: 'telegram',
-                capabilities: { streaming: true, typing: true, maxMessageLength: 4096 },
-                async sendMessage(_chatId, msgText) {
-                    const sent = await sendMd(peer, msgText);
-                    if (!sent)
+            const stopTyping = startTypingPeer(peer);
+            try {
+                const chatId = String(event.chatId ?? '?');
+                const userId = message.senderId?.toString() ?? '?';
+                const incomingMsgId = String(message.id);
+                const replyTo = message.replyTo?.replyToMsgId ?? null;
+                let replyToId = replyTo != null ? String(replyTo) : null;
+                const nowMs = Date.now();
+                if (!replyToId) {
+                    const prev = lastByChat.get(chatId);
+                    if (prev && nowMs - prev.ts < (await replyWindowMs()))
+                        replyToId = prev.msgId;
+                }
+                lastByChat.set(chatId, { msgId: incomingMsgId, ts: nowMs });
+                let displayName;
+                try {
+                    const s = (await message.getSender());
+                    displayName = s?.firstName || s?.username || undefined;
+                }
+                catch {
+                }
+                await recordUser({ chatId, msgId: incomingMsgId, sender: displayName, text, ts: message.date ?? 0, replyToId });
+                const fetch = async (id) => {
+                    try {
+                        const arr = (await tg.getMessages(peer, { ids: [Number(id)] }));
+                        const m = arr?.[0];
+                        if (!m)
+                            return null;
+                        return {
+                            text: m.message ?? '',
+                            senderId: m.senderId?.toString() ?? '',
+                            replyToId: m.replyTo?.replyToMsgId?.toString() ?? null,
+                            date: m.date ?? 0,
+                        };
+                    }
+                    catch {
                         return null;
-                    return { msgId: String(sent.id) };
-                },
-                async editMessage(_chatId, msgId, msgText) {
-                    await editMd(peer, Number(msgId), msgText);
-                },
-                startTyping(_chatId) {
-                    return startTypingPeer(peer);
-                },
-            };
-            await handleIncoming(connector, {
-                chatId,
-                userId,
-                text,
-                replyToId: replyTo != null ? String(replyTo) : null,
-            });
+                    }
+                };
+                const messages = await buildChain(incomingMsgId, { chatId, fetch, botId: meId ?? '' });
+                const connector = {
+                    id: 'telegram',
+                    capabilities: { streaming: true, typing: true, maxMessageLength: 4096 },
+                    async sendMessage(_chatId, msgText) {
+                        const sent = await sendHtml(peer, msgText, Number(incomingMsgId));
+                        if (!sent)
+                            return null;
+                        return { msgId: String(sent.id) };
+                    },
+                    async editMessage(_chatId, editId, msgText) {
+                        await editHtml(peer, Number(editId), msgText);
+                    },
+                    startTyping(_chatId) {
+                        return () => { };
+                    },
+                    async recordAssistant(m) {
+                        await recordAssistant({ ...m, chatId, now: Math.floor(Date.now() / 1000) });
+                        if (m.botMsgId)
+                            lastByChat.set(chatId, { msgId: m.botMsgId, ts: Date.now() });
+                    },
+                };
+                await handleIncoming(connector, {
+                    connectorId: 'telegram',
+                    chatId,
+                    channelSystem: TELEGRAM_FORMAT,
+                    sender: { id: userId, displayName },
+                    messages,
+                });
+            }
+            finally {
+                stopTyping();
+            }
         }
         catch (err) {
             log.error(`message handling: ${err instanceof Error ? err.message : String(err)}`);

package/dist/runtime/chain-store.d.ts

@@ -0,0 +1,28 @@
+import type { ConvMessage } from '@coffer-org/plugin-orchestrator/runtime';
+export type FetchMsg = (msgId: string) => Promise<{
+    text: string;
+    senderId: string;
+    replyToId: string | null;
+    date: number;
+} | null>;
+export declare function recordUser(m: {
+    chatId: string;
+    msgId: string;
+    sender?: string | null;
+    text: string;
+    ts: number;
+    replyToId: string | null;
+}): Promise<void>;
+export declare function recordAssistant(m: {
+    chatId: string;
+    parentMsgId: string | null;
+    botMsgId: string | null;
+    text: string;
+    now: number;
+}): Promise<void>;
+export declare function buildChain(headMsgId: string, opts: {
+    chatId: string;
+    fetch: FetchMsg;
+    botId: string;
+    maxDepth?: number;
+}): Promise<ConvMessage[]>;

package/dist/runtime/chain-store.js

@@ -0,0 +1,46 @@
+import { getThreadMessage, putThreadMessage } from '@coffer-org/server/thread-store';
+import { getLogger } from '@coffer-org/sdk/logger';
+const log = getLogger('telegram');
+const CONNECTOR = 'telegram';
+const DEFAULT_MAX_DEPTH = 30;
+export async function recordUser(m) {
+    await putThreadMessage({ connector: CONNECTOR, chatId: m.chatId, msgId: m.msgId, role: 'user', sender: m.sender ?? null, text: m.text, ts: m.ts, replyToId: m.replyToId });
+}
+export async function recordAssistant(m) {
+    if (m.botMsgId == null)
+        return;
+    await putThreadMessage({
+        connector: CONNECTOR,
+        chatId: m.chatId,
+        msgId: m.botMsgId,
+        role: 'assistant',
+        text: m.text,
+        ts: m.now,
+        replyToId: m.parentMsgId,
+    });
+}
+export async function buildChain(headMsgId, opts) {
+    const max = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const acc = [];
+    let cur = headMsgId;
+    const seen = new Set();
+    while (cur && acc.length < max && !seen.has(cur)) {
+        seen.add(cur);
+        let stored = await getThreadMessage(CONNECTOR, opts.chatId, cur);
+        if (!stored) {
+            const fetched = await opts.fetch(cur);
+            if (!fetched)
+                break;
+            const role = fetched.senderId === opts.botId ? 'assistant' : 'user';
+            await putThreadMessage({ connector: CONNECTOR, chatId: opts.chatId, msgId: cur, role, sender: null, text: fetched.text, ts: fetched.date, replyToId: fetched.replyToId });
+            stored = { msgId: cur, role, sender: null, text: fetched.text, ts: fetched.date, replyToId: fetched.replyToId };
+        }
+        acc.push({ role: stored.role, content: stored.text, sender: stored.sender, msgId: stored.msgId, ts: stored.ts });
+        cur = stored.replyToId;
+    }
+    if (acc.length >= max)
+        log.info(`chain capped at ${max} for ${headMsgId}`);
+    while (acc.length && acc.at(-1)?.role !== 'user')
+        acc.pop();
+    return acc.reverse();
+}

package/dist/runtime/index.js

@@ -1,7 +1,9 @@
 import { getPluginSettings } from '@coffer-org/server/plugin-runtime';
+import { pruneThreadMessages } from '@coffer-org/server/thread-store';
 import { startBot, stopBot } from "./bot.js";
 import { getLogger } from '@coffer-org/sdk/logger';
 const log = getLogger('telegram');
+const THREAD_TTL_MS = Number(process.env['TELEGRAM_THREAD_TTL_MS'] ?? 7 * 86_400_000);
 export { startBot, stopBot };
 export { loadBotConfig, hasCredentials } from "./config.js";
 export const serverHooks = {
@@ -12,4 +14,13 @@ export const serverHooks = {
     teardown: async () => {
         await stopBot();
     },
+    backgroundTasks: [
+        {
+            name: 'telegram-thread-prune',
+            intervalMs: 86_400_000,
+            run: async () => {
+                await pruneThreadMessages('telegram', Math.floor((Date.now() - THREAD_TTL_MS) / 1000));
+            },
+        },
+    ],
 };

package/dist/schema.js

@@ -21,14 +21,14 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-//#region ../sdk/dist/plugin.js
+//#region ../sdk/src/plugin.ts
 function definePlugin(p) {
 	if (!p.id) throw new Error("[plugin] missing id");
 	if (!p.version) console.warn(`[plugin] ${p.id}: missing version`);
 	return p;
 }
 //#endregion
-//#region ../sdk/dist/settings.js
+//#region ../sdk/src/settings.ts
 function defineSettings(s) {
 	return s;
 }
@@ -154,7 +154,10 @@ function assignProp(target, prop, value) {
 }
 function mergeDefs(...defs) {
 	const mergedDescriptors = {};
-	for (const def of defs) Object.assign(mergedDescriptors, Object.getOwnPropertyDescriptors(def));
+	for (const def of defs) {
+		const descriptors = Object.getOwnPropertyDescriptors(def);
+		Object.assign(mergedDescriptors, descriptors);
+	}
 	return Object.defineProperties({}, mergedDescriptors);
 }
 function esc(str) {
@@ -476,7 +479,7 @@ var _parse = (_Err) => (schema, value, _ctx, _params) => {
 	}, ctx);
 	if (result instanceof Promise) throw new $ZodAsyncError();
 	if (result.issues.length) {
-		const e = new (_params?.Err ?? _Err)(result.issues.map((iss) => finalizeIssue(iss, ctx, config())));
+		const e = new ((_params?.Err) ?? _Err)(result.issues.map((iss) => finalizeIssue(iss, ctx, config())));
 		captureStackTrace(e, _params?.callee);
 		throw e;
 	}
@@ -493,7 +496,7 @@ var _parseAsync = (_Err) => async (schema, value, _ctx, params) => {
 	}, ctx);
 	if (result instanceof Promise) result = await result;
 	if (result.issues.length) {
-		const e = new (params?.Err ?? _Err)(result.issues.map((iss) => finalizeIssue(iss, ctx, config())));
+		const e = new ((params?.Err) ?? _Err)(result.issues.map((iss) => finalizeIssue(iss, ctx, config())));
 		captureStackTrace(e, params?.callee);
 		throw e;
 	}
@@ -1589,13 +1592,13 @@ var $ZodObject = /*@__PURE__*/ $constructor("$ZodObject", (inst, def) => {
 		}
 		return propValues;
 	});
-	const isObject$1 = isObject;
+	const isObject$2 = isObject;
 	const catchall = def.catchall;
 	let value;
 	inst._zod.parse = (payload, ctx) => {
 		value ?? (value = _normalized.value);
 		const input = payload.value;
-		if (!isObject$1(input)) {
+		if (!isObject$2(input)) {
 			payload.issues.push({
 				expected: "object",
 				code: "invalid_type",
@@ -1718,7 +1721,7 @@ var $ZodObjectJIT = /*@__PURE__*/ $constructor("$ZodObjectJIT", (inst, def) => {
 		return (payload, ctx) => fn(shape, payload, ctx);
 	};
 	let fastpass;
-	const isObject$2 = isObject;
+	const isObject$1 = isObject;
 	const jit = !globalConfig.jitless;
 	const fastEnabled = jit && allowsEval.value;
 	const catchall = def.catchall;
@@ -1726,7 +1729,7 @@ var $ZodObjectJIT = /*@__PURE__*/ $constructor("$ZodObjectJIT", (inst, def) => {
 	inst._zod.parse = (payload, ctx) => {
 		value ?? (value = _normalized.value);
 		const input = payload.value;
-		if (!isObject$2(input)) {
+		if (!isObject$1(input)) {
 			payload.issues.push({
 				expected: "object",
 				code: "invalid_type",
@@ -1945,7 +1948,7 @@ var $ZodOptional = /*@__PURE__*/ $constructor("$ZodOptional", (inst, def) => {
 	inst._zod.optin = "optional";
 	inst._zod.optout = "optional";
 	defineLazy(inst._zod, "values", () => {
-		return def.innerType._zod.values ? new Set([...def.innerType._zod.values, void 0]) : void 0;
+		return def.innerType._zod.values ? /* @__PURE__ */ new Set([...def.innerType._zod.values, void 0]) : void 0;
 	});
 	defineLazy(inst._zod, "pattern", () => {
 		const pattern = def.innerType._zod.pattern;
@@ -1979,7 +1982,7 @@ var $ZodNullable = /*@__PURE__*/ $constructor("$ZodNullable", (inst, def) => {
 		return pattern ? new RegExp(`^(${cleanRegex(pattern.source)}|null)$`) : void 0;
 	});
 	defineLazy(inst._zod, "values", () => {
-		return def.innerType._zod.values ? new Set([...def.innerType._zod.values, null]) : void 0;
+		return def.innerType._zod.values ? /* @__PURE__ */ new Set([...def.innerType._zod.values, null]) : void 0;
 	});
 	inst._zod.parse = (payload, ctx) => {
 		if (payload.value === null) return payload;
@@ -4078,7 +4081,7 @@ function number(params) {
 	return /* @__PURE__ */ _coercedNumber(ZodNumber, params);
 }
 //#endregion
-//#region ../sdk/dist/units.js
+//#region ../sdk/src/units.ts
 var UNITS_CURRENCY = [
 	{
 		value: "UAH",
@@ -4386,7 +4389,13 @@ function resolveUnits(u) {
 	return typeof u === "string" ? UNITS_MAP[u] : u;
 }
 //#endregion
-//#region ../sdk/dist/currencies.js
+//#region ../sdk/src/currencies.ts
+/**
+* Валюти з вбудованого `Intl` (ISO 4217) — БЕЗ hand-list і без npm-залежності.
+* Коди — `Intl.supportedValuesOf('currency')`; символи/назви локалізовані через
+* `Intl.NumberFormat`/`Intl.DisplayNames`.
+*/
+/** Усі ISO 4217 коди. Fallback — кілька основних (на випадок старого рантайму). */
 var CURRENCY_CODES = (() => {
 	try {
 		return Intl.supportedValuesOf("currency");
@@ -4401,24 +4410,34 @@ var CURRENCY_CODES = (() => {
 	}
 })();
 var CODE_SET = new Set(CURRENCY_CODES);
+/** Чи валідний ISO 4217 код. */
 var isCurrencyCode = (c) => CODE_SET.has(c);
 //#endregion
-//#region ../sdk/dist/fields/validation.js
+//#region ../sdk/src/fields/validation.ts
+/** Структуроване повідомлення для zod: JSON {code, params}. Декодує mutate.ts. */
 function vmsg(code, params) {
 	return JSON.stringify(params ? {
 		code,
 		params
 	} : { code });
 }
+/** v4 error-map: повідомлення для відсутнього значення (колишній required_error). */
 function reqErr(code = "required") {
 	return { error: (iss) => iss.input === void 0 ? vmsg(code) : void 0 };
 }
+/** v4 error-map: повідомлення для невалідного типу (колишній invalid_type_error). */
 function typeErr(code = "invalid_type") {
 	return { error: (iss) => iss.code === "invalid_type" ? vmsg(code) : void 0 };
 }
+/** v4 error-map: required + invalid_type разом (колишні required_error + invalid_type_error). */
 function reqTypeErr() {
 	return { error: (iss) => iss.code === "invalid_type" ? iss.input === void 0 ? vmsg("required") : vmsg("invalid_type") : void 0 };
 }
+/** Parse a JSON string, else return the native value (object/array) as-is.
+*  Tolerant input for native form-state AND legacy JSON-string payloads.
+*  A string that fails JSON.parse is returned unchanged — callers detect
+*  parse failure via `typeof result === 'string'` (inners here are object/array,
+*  never a bare string). */
 function jsonValue(raw) {
 	if (typeof raw === "string") try {
 		return JSON.parse(raw);
@@ -4427,6 +4446,12 @@ function jsonValue(raw) {
 	}
 	return raw;
 }
+/**
+* Фабрика для полів, що зберігають JSON і валідуються вкладеною zod-схемою.
+* Приймає нативне object/array (native form-state) АБО JSON-рядок (legacy).
+* Single-parse через jsonValue → inner.safeParse → issue `code`; рядок, що не
+* розпарсився, лишається рядком → код 'json'.
+*/
 function jsonRefined(inner, code) {
 	return unknown().superRefine((raw, ctx) => {
 		const parsed = jsonValue(raw);
@@ -4455,7 +4480,7 @@ function optionalize(schema, required) {
 	}).pipe(schema));
 }
 //#endregion
-//#region ../sdk/dist/fields/normalize.js
+//#region ../sdk/src/fields/normalize.ts
 function normalizeOpts(rawIn) {
 	const raw = rawIn;
 	const r = raw.rules ?? {};
@@ -4495,7 +4520,19 @@ function normalizeOpts(rawIn) {
 	return Object.fromEntries(Object.entries(result).filter(([, v]) => v !== void 0));
 }
 //#endregion
-//#region ../sdk/dist/field-presets.js
+//#region ../sdk/src/field-presets.ts
+/**
+* Пресети полів — тонкі обгортки над базовими примітивами з fields.ts.
+*
+* Кожен пресет = один kind (один віджет). Пресети не приймають `format` —
+* вони самі є семантичними типами. min/max/step — через `config`.
+*
+* Пресети додаються до `f` через `composeF`, який гарантує, що жоден пресет
+* не перебиває примітив.
+*
+* Циклічний імпорт з fields.ts безпечний: фабрики/хелпери — hoisted-декларації,
+* а пресети викликають їх лише в тілі своїх функцій.
+*/
 function email(raw) {
 	const o = normalizeOpts(raw);
 	const required = o.required ?? false;
@@ -4549,6 +4586,14 @@ function password(raw) {
 		zod: optionalize(s, required)
 	});
 }
+/**
+* Internal API-token list — keyValue-shaped collection (name + write-only
+* token + timestamps), custom renderer (`kind:'internalApiToken'`, own
+* create/revoke UI — same trick as url()/perWeekday()). "Internal" = not a
+* general-purpose field type for plugin shelves, only for the core account
+* settings page. `token` is `kind:'password'` so maskSecrets/preserveTree
+* already mask/preserve it for free.
+*/
 function internalApiToken(o) {
 	return group({
 		key: o.key,
@@ -4641,8 +4686,10 @@ function link(raw) {
 	}, o.multiple ?? false));
 }
 var TEL_RE = /^\+?[\d\s()-]{4,}$/;
+/** Loose URL: будь-який scheme:// АБО host-з-крапкою (+опц. порт/шлях). Без пробілів. */
 var LINK_RE = /^([a-z][a-z0-9+.-]*:\/\/\S+|[\w-]+(\.[\w-]+)+(:\d+)?(\/\S*)?)$/i;
-var CSS_COLOR_NAMES = new Set([
+/** CSS named colors (CSS Color Module L4) — для f.colorname. */
+var CSS_COLOR_NAMES = /* @__PURE__ */ new Set([
 	"aliceblue",
 	"antiquewhite",
 	"aqua",
@@ -4900,6 +4947,7 @@ function reminder(raw) {
 }
 var _real = real;
 var _int = int;
+/** Відсоток 0..100 — real з rules:{min:0,max:100}. */
 function percent(o) {
 	return _real({
 		...o,
@@ -4910,6 +4958,7 @@ function percent(o) {
 		}
 	});
 }
+/** Рік — int з rules:{min:1900,max:2100}; межі можна перекрити через rules.min/max. */
 function year(o) {
 	return _int({
 		...o,
@@ -5101,7 +5150,7 @@ var require_data = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		},
 		cs: {
 			name: "Czech",
-			nativeName: "Čeština"
+			nativeName: "čeština"
 		},
 		cu: {
 			name: "Old Church Slavonic",
@@ -5565,7 +5614,7 @@ var require_data = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		},
 		sk: {
 			name: "Slovak",
-			nativeName: "Slovenčina"
+			nativeName: "slovenčtina"
 		},
 		sl: {
 			name: "Slovenian",
@@ -5730,7 +5779,7 @@ var require_data = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	};
 }));
 //#endregion
-//#region ../sdk/dist/fields/constants.js
+//#region ../sdk/src/fields/constants.ts
 var import_src = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var LANGUAGES_LIST = require_data();
 	var LANGUAGES = {};
@@ -5786,7 +5835,21 @@ import_src.default.getAllCodes().map((code) => ({
 	name: import_src.default.getNativeName(code)
 })).sort((a, b) => a.name.localeCompare(b.name));
 //#endregion
-//#region ../sdk/dist/fields.js
+//#region ../sdk/src/fields.ts
+/**
+* The field type system — the heart of the platform. A pure, isomorphic module.
+* One field description → three consumers:
+*   1. `zod`    — validation (identical on server and client)
+*   2. `column` — the DB column type
+*   3. `prim`/`kind` — keys for resolving the renderer (see web/render/registry)
+*/
+/**
+* A visual or storage group of fields (one level of nesting — no groups inside groups).
+* Without `key` → a layout group (not stored). With `key` → storage:
+*   - embedded (key, no multiple): stored as a column or a nested object.
+*   - collection (key + multiple): a child table (array of rows).
+* A storage group requires a `label` and only `FieldItem` children (with a storage key).
+*/
 function group(o) {
 	const r = o.rules ?? {};
 	const v = o.view ?? {};
@@ -5809,6 +5872,7 @@ function group(o) {
 		fields: o.fields
 	};
 }
+/** Layout group, flow nowrap + horizontal scroll (single line). Sugar over group(). */
 function row(o) {
 	return group({
 		label: o.label,
@@ -5819,6 +5883,7 @@ function row(o) {
 		}
 	});
 }
+/** Tabular collection (array of rows → <table>, aligned by columns). Sugar. */
 function table(o) {
 	return group({
 		key: o.key,
@@ -5833,6 +5898,11 @@ function table(o) {
 		}
 	});
 }
+/**
+* Layout group with a 2D layout (rows×columns → aligned CSS grid).
+* Keyless (flat parent fields). Rows are glued together with brk() separators
+* into a flat fields; the renderer reconstructs the 2D by splitting on brk. Sugar over group().
+*/
 function sheet(o) {
 	const flat = [];
 	o.fields.forEach((rowFields, i) => {
@@ -5848,6 +5918,12 @@ function sheet(o) {
 		}
 	});
 }
+/**
+* Composite URL — embedded-group sugar. Storage: separate nested columns
+* (`key__scheme`, `key__host`, `key__port`, …) in the same table. The renderer
+* is custom (a single link/input, `kind:'url'`) — string↔parts via
+* parseUrl/buildUrl. Partial/invalid URLs are stored by parts.
+*/
 function url(o) {
 	return group({
 		key: o.key,
@@ -5881,18 +5957,22 @@ function keyed(o) {
 		fixed: o.fixed
 	};
 }
+/** Horizontal divider. */
 function divider() {
 	return { el: "divider" };
 }
+/** Forced flow-row wrap (subsequent fields start on a new row). No <hr>. */
 function brk() {
 	return { el: "break" };
 }
+/** Reference markdown block by i18n key. */
 function info(textKey) {
 	return {
 		el: "info",
 		text: textKey
 	};
 }
+/** Action button: invokes the handler registered in actionRegistry under the key `value`. */
 function button(o) {
 	return {
 		el: "button",
@@ -5902,6 +5982,7 @@ function button(o) {
 		variant: o.variant
 	};
 }
+/** Wraps FieldMeta into FieldItem/StaticEl depending on opts.key/opts.value. */
 function wrapKey(opts, meta) {
 	let m = meta;
 	if (opts.noEditControl) m = {
@@ -5911,6 +5992,34 @@ function wrapKey(opts, meta) {
 			noEditControl: true
 		}
 	};
+	if (opts.emphasis) m = {
+		...m,
+		hints: {
+			...m.hints,
+			emphasis: opts.emphasis
+		}
+	};
+	if (opts.noLabel) m = {
+		...m,
+		hints: {
+			...m.hints,
+			noLabel: true
+		}
+	};
+	if (opts.role) m = {
+		...m,
+		hints: {
+			...m.hints,
+			role: opts.role
+		}
+	};
+	if (opts.pinned) m = {
+		...m,
+		hints: {
+			...m.hints,
+			pinned: true
+		}
+	};
 	if (opts.default !== void 0) m = {
 		...m,
 		default: opts.default
@@ -5940,6 +6049,14 @@ function safeJsonParse(s) {
 		return;
 	}
 }
+/**
+* Wraps a field into a JSON array of values (storage: TEXT). The inner zod is `base.zod`.
+* Modifier order: base → applyMultiple.
+*
+* Exception: kind 'image'/'media' handle multiple themselves in the renderer (gallery) —
+* the MultipleField* wrappers on the web skip them.
+*/
+/** Zod "JSON array of inner values" — shared by applyMultiple and bindSelectSourceZod. */
 function multipleZod(inner) {
 	return unknown().superRefine((raw, ctx) => {
 		let arr;
@@ -6266,8 +6383,8 @@ function relation(raw) {
 			displayKey: o.displayKey ?? "name"
 		},
 		relation: {
-			vault: raw.options.vault,
-			type: raw.options.module
+			library: raw.options.library,
+			type: raw.options.shelf
 		},
 		...multi && { json: true },
 		zod: optionalize(s, required)
@@ -6532,6 +6649,11 @@ function geo(raw) {
 		zod: optionalize(s, required)
 	});
 }
+/**
+* 7 values, Mon–Sun. A thin wrapper over keyed({fixed}): a fixed collection,
+* by=select('weekdays'), one real value per day. Its own kind 'per-weekday'
+* dispatches a compact renderer. Storage: a grandchild table of {day, value} rows.
+*/
 function perWeekday(o) {
 	return {
 		...keyed({
@@ -6824,6 +6946,11 @@ function embed(raw) {
 		zod: optionalize(s, required)
 	});
 }
+/**
+* Base primitives (storage-aligned) + structural types. Presets (thin wrappers
+* over these primitives) are added below from field-presets.ts and CANNOT override
+* any key from here (guard in composeF).
+*/
 var PRIMITIVES = {
 	string,
 	text,
@@ -6873,6 +7000,7 @@ var PRIMITIVES = {
 	info,
 	button
 };
+/** Assembles `f`, guaranteeing no preset shadows a primitive. */
 function composeF(presets) {
 	for (const k of Object.keys(presets)) if (k in PRIMITIVES) throw new Error(`[f] preset '${k}' overrides a primitive`);
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/plugin-telegram",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -25,11 +25,11 @@
     "test": "node --import tsx --test \"src/runtime/*.test.ts\""
   },
   "dependencies": {
-    "@coffer-org/plugin-orchestrator": "^1.3.1",
-    "@coffer-org/sdk": "^1.4.0",
-    "@coffer-org/server": "^1.4.0",
+    "@coffer-org/plugin-orchestrator": "^1.4.0",
+    "@coffer-org/sdk": "^1.5.0",
+    "@coffer-org/server": "^1.8.0",
     "input": "^1.0.1",
-    "telegram": "^2.26.0"
+    "teleproto": "^1.228.1"
   },
   "devDependencies": {},
   "coffer": {