@adriangalilea/utils 1.2.0 → 1.4.0

package/README.md

@@ -359,6 +359,17 @@ await ctx.say.edit({ en: 'Done', es: 'Listo' })    // → ctx.editText (callback
 await ctx.say.answer({ en: 'OK', es: 'OK' })       // → ctx.answer (callback only)
 ```
 
+### Telegram HTML (`tg-html`)
+
+Transform arbitrary (LLM-emitted) HTML into Telegram-compatible `parse_mode=HTML` with opinionated, consistent spacing. Telegram's HTML subset has no headings, lists, or block layout — send it `<h1>`/`<ul>` and the API rejects the whole message. `transform()` accepts the HTML a model naturally writes and renders the structure typographically: `h1` → bold+underline + blank line, `h2…h6` → bold + blank line, `ul/li` → `• ` bullets, blocks get blank lines, blockquotes keep their internal line breaks, allowed tags pass through with attributes filtered, unknown tags drop their markup (content kept), and stray `<`/`>` escape instead of vanishing. Zero dependencies, no DOM, Worker-safe. Successor of the standalone `tghtml` package (jsr, archived).
+
+```typescript
+import { transform } from '@adriangalilea/utils/tg-html'
+
+transform('<h1>Title</h1><ul><li>Point one</li><li>Point two</li></ul>')
+// '<b><u>Title</u></b>\n\n• Point one\n• Point two'
+```
+
 ### Telegram bot plugins (GramIO)
 
 Plugins for personal Telegram bots built on [GramIO](https://gramio.dev). Each plugin lives at its own subpath; peer deps (`gramio`, `@gramio/storage`, `@gramio/session`, `@gramio/format`, `marked`) are **all optional** — install only what you import.
@@ -429,12 +440,13 @@ Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc.
 | `@adriangalilea/utils/bot/kit` | The Node-only corner. `gracefulStart(bot, opts?)` — SIGINT/SIGTERM → `bot.stop()` → exit; force-kills if shutdown hangs. DMs the admin `@<bot> started.` / `@<bot> shutting down.` by default when `KEV.TELEGRAM_ADMIN_ID` is set (graceful only — crashes don't trigger `onStop`); pass `notifyAdmin: false` to disable or `notifyAdmin: 12345` for an explicit chat id.<br>`adminContext({ adminId? })` — reads `TELEGRAM_ADMIN_ID` from `kev` (with optional hardcoded fallback), decorates `ctx.adminId` + `ctx.isAdmin`.<br>Also re-exports `botSession` / `prefixStorage` from `bot/session` so Node consumers keep one import. |
 | `@adriangalilea/utils/bot/session` | `botSession(opts)` — **drop-in replacement for `@gramio/session`'s `session()`** that auto-namespaces every key as `bot-<id>:<senderId>` using `ctx.bot.info.id` (populated by `getMe()` at startup). Use this instead of `session()` — full stop. Multiple bots sharing one Redis/D1 stay isolated by construction; every plugin in this package derives the same prefix internally via `botStorageKey(ctx, userId)` / `botSubKey(ctx, sub)` (from `bot/keys`). No regex, no manual prefix argument, no way to forget.<br>`prefixStorage(storage, prefix)` — escape hatch for adding a top-level prefix on top of the bot-id namespace; almost never needed. Worker-safe (used to live in `bot/kit`, which forced Worker bots to hand-roll the keying). |
 | `@adriangalilea/utils/bot/notify` | Best-effort admin DMs, worker-safe (you pass the ids; no env, no process). `notifyAdmins(bot, adminIds, text, extra?)` — DM each admin, failures logged and swallowed (a notification must never take the bot down). `alertAdminError(bot, adminIds, label, error, throttle?)` — truncated `🚨 label\nName: message`, rate-limited through a caller-owned `alertThrottle(ms?)` so a failure storm sends one alert per window. `gracefulStart`'s start/stop DMs are built on this. |
+| `@adriangalilea/utils/bot/profile` | `syncBotProfile(bot, { name?, description?, about?, commands?, expects?, adminIds? })` — the bot's Telegram-facing identity as CODE, never BotFather: localized name / description / About / public command list, reconciled idempotently on every boot (get → compare → set per field per language; unchanged values cost one read, so cold-start firing is rate-limit-free). `expects: { inline: true }` declares the BotFather-only capabilities the code assumes — a mismatch (inline mode off on an inline-dependent bot) DMs the admins, since the API can only detect it, not fix it. Never throws; failures log and the bot keeps running. |
 | `@adriangalilea/utils/bot/access-control` | Personal-bot ACL — gates non-admin/non-default users; admin gets DM with `[✅ Aprobar][❌ Denegar]` on first attempt; `/access` opens a persistent menu (revoke / reapprove / list pending). Backed by `@gramio/session` per-user + a small index. **Native alternative**: BotFather → Bot Settings → Access → "Restrict bot usage" — flat allow-list at Telegram. Use this plugin when you want in-bot approval flow instead of a BotFather round-trip; both can coexist. |
 | `@adriangalilea/utils/bot/allow-list` | Static allow-list by **id and/or @username** — stateless, no session/storage. `allowList({ ids?, usernames? })` is a plugin that decorates `ctx.allowed` (boolean); gate in your handlers (`if (!ctx.allowed) return`). `makeAllowList(...)` is the pure framework-free predicate. The light counterpart to `access-control` (which adds an approve/deny flow + revocable store, needing session+storage). Username caveat: a `@username` is optional and mutable, and the Bot API can't resolve username→id ahead of time — prefer `ids` when known, `usernames` is the pragmatic fallback. |
 | `@adriangalilea/utils/bot/coalesce` | Joins client-split inbound messages back into one. When a user pastes >4096 chars, Telegram clients fragment it into separate `message` updates with no marker. Middleware detects the burst and emits one combined event. |
 | `@adriangalilea/utils/bot/llm` | The full LLM-chatbot pipeline in one module. **Input:** `streamChat(response)` parses OpenAI-compatible SSE (OpenAI, vllm, mlx-lm, llama.cpp, Together, Groq, …) into a typed `AsyncGenerator<{type: 'content' \| 'reasoning', text}>`. **Output:** `ctx.startStream()` (low-level: debounced markdown to Telegram, 4000-char split, exposes `wasPartial` after `.end()`). `ctx.startChatStream(response)` (high-level: consumes the stream, renders reasoning as a Telegram `expandable_blockquote` entity + content as streamed markdown — both go through `markdownToFormattable` with graceful degradation — returns `{ content, reasoning }`). **History:** `llmHistory({...})` returns `.plugin` (decorates `ctx.llm` with `.add() / .get() / .clear() / .all() / .clearAll()`, per-(user, thread) OpenAI `ChatMessage` shape, persisted in the shared session record so the menu's 🗑 Forget wipes it automatically) AND `.menuItem` (drop-in "🗑 Delete this thread" for `botMenu` — wipes the LLM history AND calls `deleteForumTopic` so the Telegram thread + all its messages disappear from the chat; falls back to Redis-only clear when no `threadId` is present). |
 | `@adriangalilea/utils/bot/menu` | `botMenu({ command, description, items, privacy?, personalData?, adminContact })` — `/settings` command + InlineKeyboard router. Root view always renders a `🛡️ Privacy & data` submenu button that wraps the privacy policy link plus (if `personalData: { storage }`) 🗑 Forget + 📥 Export buttons. Items take `keepRow` (render on the same row as the next item — e.g. a two-per-row language picker) and `rootExtra` (render at the bottom of the root menu, below Privacy & data). `label` / `header` / `style` / `visible` resolvers may be **async** (read your db at render time — never cache render strings in the session); `parseMode: 'HTML'` renders the header formatted (you own escaping); `personalData.onForget(ctx, userId)` wipes YOUR tables inside the same try as the session delete, so Forget either forgets everything or reports failure. `toggleMenuItem({ id, read, write, label: { off, on }, toast? })` — convenience factory for boolean-toggle items with dynamic label + optional toast, storage-agnostic via `read`/`write` closures. |
-| `@adriangalilea/utils/bot/payments` | `botPayments({ session, storage, paysupport, paysupportHint?, legal, waiver, vip?, credits?, perks? })` — Telegram Stars monetization in one drop-in plugin. **Three axes, all optional:** `vip` (positional tier ladder — single rung in v1 is just `vip: [{...}]`, ladder is `vip: [{...}, {...}]`; ids are `vip.1`, `vip.2`, …), `credits` (consumable balance + top-up packs `credits.1`, `credits.2`, …), `perks` (orthogonal one-shot unlocks `perks.<key>`). **Surface:** `ctx.payments.atLeast('vip')` / `atLeast('vip.2')` (typed rank check), `ctx.payments.tier()` / `.tier.level()` / `.tier.label()`, `ctx.payments.credits.{balance, consume, tryConsume}` (throws `InsufficientCredits`), `ctx.payments.has(perkId)`, `await ctx.payments.require('vip', { feature? })` (gate that sends a localized upgrade prompt deep-linked to `/settings → 💎 VIP`), `await ctx.payments.invoice(productKey)` (threads Art. 103(m) TRLGDCU consent inline before `sendInvoice`). **Owns:** waiver consent flow (versioned text → forces re-consent on bump, snapshotted on every charge for audit), `/paysupport` slash command (Telegram ToS §6.5; `paysupportHint` overrides the where-to-manage-charges line when your menu isn't `/settings`), idempotent `successful_payment` fulfillment via `pay:idempotency:{chargeId}` sentinel, lazy subscription expiry (no cron needed), tier upgrade auto-cancel of the lower rung's renewal, and admin-DM refund approval (mirror of `accessControl`'s [✅ Aprobar][❌ Denegar] pattern). **Returns:** `{ plugin, menuItem, payouts, onFulfilled }` — `menuItem` is the drop-in `💎 VIP` entry for `botMenu`; `payouts.{record, list, export, exportForUsers}` is the Fragment payout ledger (you receive TON, log the EUR conversion, export time-windowed CSV/JSON for your gestor); `onFulfilled(productKey \| '*', handler)` registers fire-and-forget hooks. **Stars-only by design** — Telegram ToS §6.2 forbids third-party payment providers for digital goods. Crypto Pay deferred (MiCA risk); Stripe-outside-Telegram is a future v2 channel. Full compliance memo (Spanish-autónomo seller-of-record analysis, Verifactu vs Crea y Crece, MiCA, Art. 103(m) waiver text, GDPR retention) in `src/bot/payments/CLAUDE.md`. |
+| `@adriangalilea/utils/bot/payments` | `botPayments({ session, storage, paysupport, paysupportHint?, legal, waiver, vip?, credits?, perks? })` — Telegram Stars monetization in one drop-in plugin. **Three axes, all optional:** `vip` (positional tier ladder — single rung in v1 is just `vip: [{...}]`, ladder is `vip: [{...}, {...}]`; ids are `vip.1`, `vip.2`, …), `credits` (consumable balance + top-up packs `credits.1`, `credits.2`, …), `perks` (orthogonal one-shot unlocks `perks.<key>`). **Surface:** `ctx.payments.atLeast('vip')` / `atLeast('vip.2')` (typed rank check), `ctx.payments.tier()` / `.tier.level()` / `.tier.label()`, `ctx.payments.credits.{balance, consume, tryConsume}` (throws `InsufficientCredits`), `ctx.payments.has(perkId)`, `await ctx.payments.require('vip', { feature? })` (gate that sends a localized upgrade prompt deep-linked to `/settings → 💎 VIP`), `await ctx.payments.invoice(productKey)` (threads Art. 103(m) TRLGDCU consent inline before `sendInvoice`). **Owns:** waiver consent flow (versioned text → forces re-consent on bump, snapshotted on every charge for audit), `/paysupport` slash command (Telegram ToS §6.5; `paysupportHint` overrides the where-to-manage-charges line when your menu isn't `/settings`), idempotent `successful_payment` fulfillment via `pay:idempotency:{chargeId}` sentinel, lazy subscription expiry (no cron needed), tier upgrade auto-cancel of the lower rung's renewal, and admin-DM refund approval (mirror of `accessControl`'s [✅ Aprobar][❌ Denegar] pattern). **Returns:** `{ plugin, menuItem, payouts, onFulfilled }` — `menuItem` is the drop-in `💎 VIP` entry for `botMenu`; `payouts.{record, list, export, exportForUsers}` is the Fragment payout ledger (you receive TON, log the EUR conversion, export time-windowed CSV/JSON for your gestor); `onFulfilled(productKey \| '*', handler)` / `onRefunded(...)` register fire-and-forget hooks (purchase applied / admin-approved refund — a revenue ledger writes on one, reverses on the other). **Stars-only by design** — Telegram ToS §6.2 forbids third-party payment providers for digital goods. Crypto Pay deferred (MiCA risk); Stripe-outside-Telegram is a future v2 channel. Full compliance memo (Spanish-autónomo seller-of-record analysis, Verifactu vs Crea y Crece, MiCA, Art. 103(m) waiver text, GDPR retention) in `src/bot/payments/CLAUDE.md`. |
 | `@adriangalilea/utils/bot/create` | `createBot<S>({ token?, storage?, initial?, admins?, language?, menu?, access?, payments?, handlers?, worker? })` — the composer (see "One bot file, ideation → production" above). Returns `{ build, session, poll, isMain, fetch }`: `poll()` long-polls, `export default app` is a complete Worker, `app.session(ctx)` / the `handlers` callback's `session(ctx)` is the TYPED accessor for your `S` fields. Owns storage+session wiring; resolves storage per environment (D1 binding → `bot/storage-d1`; `BOT_PERSIST` path → sqlite, `redis://` → redis, lazily-imported optional peers; else announced-ephemeral memory) — or pass `storage: (env) => Storage` when the choice is env-dependent (e.g. a D1 binding not named `DB`). Boot NARRATES the composition (`session: memory …`, `features: language(en,es) · menu(/settings)`) so every implicit decision is visible where you're looking. Runnable demo: `pnpm demo:bot`. |
 | `@adriangalilea/utils/bot/worker` | `botWorkerFetch(resolve)` — the Cloudflare Worker cap: secret-checked webhook (ack fast, work + storage flush ride `ctx.waitUntil`, errors DM admins throttled), `POST /setup` (webhook registration with handler-derived `allowed_updates` + a commit-narrating 🚀 deploy DM from the request body), `POST /deploy-started` (the 🛳 "what is shipping" DM — curl it from your deploy script on the still-live version, body `{sha, author, message, etaSeconds?}`), operator-authed `/pause` `/resume` `/webhook-status` (+ `statusExtra`), and a `routes` escape hatch tried before the built-ins. Structural bot type — no workers-types dependency. |
 | `@adriangalilea/utils/bot/storage-d1` | `d1Storage({ db, table? })` — `@gramio/storage` adapter over a D1 `session` table (schema in the module doc). `flush()` matters: the session plugin writes un-awaited and workerd freezes the isolate the instant `fetch()` returns — hand `flush` to `bot/worker` (automatic via `createBot`) so writes survive. |

package/dist/bot/profile.d.ts

@@ -0,0 +1,59 @@
+/** One public slash command as Telegram publishes it. */
+export interface BotCommandEntry {
+    command: string;
+    description: string;
+}
+/** Per-language values; the FIRST key doubles as the unlocalized default. */
+export type Localized<T> = Record<string, T>;
+/** The structural bot surface the sync needs (satisfied by a gramio Bot). */
+export type ProfileBot = {
+    info?: {
+        username?: string;
+        supports_inline_queries?: boolean;
+    };
+    api: {
+        getMyName: (p: object) => Promise<{
+            name?: string;
+        }>;
+        setMyName: (p: object) => Promise<unknown>;
+        getMyDescription: (p: object) => Promise<{
+            description?: string;
+        }>;
+        setMyDescription: (p: object) => Promise<unknown>;
+        getMyShortDescription: (p: object) => Promise<{
+            short_description?: string;
+        }>;
+        setMyShortDescription: (p: object) => Promise<unknown>;
+        getMyCommands: (p: object) => Promise<ReadonlyArray<BotCommandEntry>>;
+        setMyCommands: (p: object) => Promise<unknown>;
+        sendMessage: (p: {
+            chat_id: number;
+            text: string;
+        }) => Promise<unknown>;
+    };
+};
+export interface BotProfileOptions {
+    /** Display name (`setMyName`, 64 chars). */
+    name?: Localized<string>;
+    /** "What can this bot do?" (`setMyDescription`, 512 chars). */
+    description?: Localized<string>;
+    /** About / short description (`setMyShortDescription`, 120 chars). */
+    about?: Localized<string>;
+    /** Public command list per language (admin commands stay out — they're behavior, not menu). */
+    commands?: Localized<ReadonlyArray<BotCommandEntry>>;
+    /**
+     * BotFather-only capabilities this bot's features assume. Checked against `getMe` on every
+     * sync; a mismatch WARNS the admins (it can't be fixed over the API, only surfaced).
+     */
+    expects?: {
+        inline?: boolean;
+    };
+    /** Admins to DM on an expectation mismatch: a plain array or a live resolver. */
+    adminIds?: readonly number[] | (() => Promise<readonly number[]> | readonly number[]);
+}
+/**
+ * Reconcile the declared profile with Telegram, field by field, language by language —
+ * writes only genuine diffs. Never throws. Call fire-and-forget after `bot.init()`.
+ */
+export declare function syncBotProfile(bot: ProfileBot, opts: BotProfileOptions): Promise<void>;
+//# sourceMappingURL=profile.d.ts.map

package/dist/bot/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/bot/profile.ts"],"names":[],"mappings":"AA0CA,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,6EAA6E;AAC7E,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;AAE7C,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG;IACxB,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,uBAAuB,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAChE,GAAG,EAAE;QACJ,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACrD,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3C,gBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;YAAE,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACnE,gBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QAClD,qBAAqB,EAAE,CACtB,CAAC,EAAE,MAAM,KACL,OAAO,CAAC;YAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC7C,qBAAqB,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QACvD,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;QACtE,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QAC/C,WAAW,EAAE,CAAC,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACxE,CAAC;CACF,CAAC;AAEF,MAAM,WAAW,iBAAiB;IACjC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAChC,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1B,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IACrD;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,EACN,SAAS,MAAM,EAAE,GACjB,CAAC,MAAM,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC;CAC1D;AAqCD;;;GAGG;AACH,wBAAsB,cAAc,CACnC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,iBAAiB,GACrB,OAAO,CAAC,IAAI,CAAC,CAkEf"}

package/dist/bot/profile.js

@@ -0,0 +1,140 @@
+/**
+ * `bot/profile` — the bot's Telegram-facing identity as CODE, synced idempotently.
+ *
+ * A bot should never depend on values typed into BotFather: name, description,
+ * About, and the public command list are all settable over the API, so they
+ * belong in the repo — reviewable, localized, and reproducible on a fresh
+ * token. `syncBotProfile` declares them once and reconciles on every boot with
+ * a get → compare → set diff-guard per field per language: unchanged values
+ * cost one read, so firing it on every Worker cold start is free of rate-limit
+ * risk. Failures are logged and swallowed — a profile hiccup must never take
+ * the bot down.
+ *
+ * What the API canNOT set, BotFather still owns: the token itself and the
+ * inline-mode switch. Those are declared as EXPECTATIONS instead — the sync
+ * checks `getMe` and DMs the admins when reality disagrees with what the code
+ * assumes (an inline-dependent bot silently losing inline mode is exactly the
+ * kind of drift nobody notices until users do).
+ *
+ * @example
+ * import { syncBotProfile } from '@adriangalilea/utils/bot/profile'
+ *
+ * void syncBotProfile(bot, {
+ *   description: { en: 'What I do…', es: 'Lo que hago…' },   // first key = the default
+ *   about:       { en: '⚡ short pitch', es: '⚡ pitch corto' },
+ *   commands: {
+ *     en: [{ command: 'start', description: 'Set up' }],
+ *     es: [{ command: 'start', description: 'Configurar' }],
+ *   },
+ *   expects: { inline: true },
+ *   adminIds: () => store.readAdminIds(ctx, []),              // live resolver or plain array
+ * })
+ */
+import { createLogger } from "../universal/log.js";
+import { notifyAdmins } from "./notify.js";
+const log = createLogger("bot/profile");
+// Telegram caps, counted in code points so emoji are one glyph each.
+const NAME_MAX = 64;
+const DESCRIPTION_MAX = 512;
+const ABOUT_MAX = 120;
+/** Count Unicode code points (emoji = 1), for Telegram's limits. */
+function glyphs(s) {
+    return [...s].length;
+}
+function commandsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return a.every((cmd, i) => cmd.command === b[i].command && cmd.description === b[i].description);
+}
+function overLimit(field, values, max) {
+    for (const [lang, value] of Object.entries(values)) {
+        if (glyphs(value) > max) {
+            log.error(`${field} (${lang}) exceeds ${max} chars — skipping ${field} sync`);
+            return true;
+        }
+    }
+    return false;
+}
+const langParam = (lang) => lang ? { language_code: lang } : {};
+/**
+ * Reconcile the declared profile with Telegram, field by field, language by language —
+ * writes only genuine diffs. Never throws. Call fire-and-forget after `bot.init()`.
+ */
+export async function syncBotProfile(bot, opts) {
+    const jobs = [];
+    const eachLang = (values, sync) => {
+        const entries = Object.entries(values);
+        if (entries.length === 0)
+            return;
+        jobs.push(sync(undefined, entries[0][1])); // first entry = the unlocalized default
+        for (const [lang, value] of entries)
+            jobs.push(sync(lang, value));
+    };
+    if (opts.name && !overLimit("name", opts.name, NAME_MAX)) {
+        eachLang(opts.name, async (lang, value) => {
+            const current = await bot.api.getMyName(langParam(lang));
+            if (current.name === value)
+                return;
+            await bot.api.setMyName({ name: value, ...langParam(lang) });
+            log.info(`name synced${lang ? ` (${lang})` : ""}`);
+        });
+    }
+    if (opts.description &&
+        !overLimit("description", opts.description, DESCRIPTION_MAX)) {
+        eachLang(opts.description, async (lang, value) => {
+            const current = await bot.api.getMyDescription(langParam(lang));
+            if (current.description === value)
+                return;
+            await bot.api.setMyDescription({
+                description: value,
+                ...langParam(lang),
+            });
+            log.info(`description synced${lang ? ` (${lang})` : ""}`);
+        });
+    }
+    if (opts.about && !overLimit("about", opts.about, ABOUT_MAX)) {
+        eachLang(opts.about, async (lang, value) => {
+            const current = await bot.api.getMyShortDescription(langParam(lang));
+            if (current.short_description === value)
+                return;
+            await bot.api.setMyShortDescription({
+                short_description: value,
+                ...langParam(lang),
+            });
+            log.info(`about synced${lang ? ` (${lang})` : ""}`);
+        });
+    }
+    if (opts.commands) {
+        eachLang(opts.commands, async (lang, list) => {
+            const current = await bot.api.getMyCommands(langParam(lang));
+            if (commandsEqual(current, list))
+                return;
+            await bot.api.setMyCommands({ commands: [...list], ...langParam(lang) });
+            log.info(`commands synced${lang ? ` (${lang})` : ""} (${list.length})`);
+        });
+    }
+    try {
+        await Promise.all(jobs);
+    }
+    catch (e) {
+        log.error(`profile sync failed: ${e instanceof Error ? e.message : e}`);
+    }
+    await checkExpectations(bot, opts).catch((e) => log.error(`expectation check failed: ${e instanceof Error ? e.message : e}`));
+}
+/** The BotFather-drift check: warn the admins when a declared capability is off. */
+async function checkExpectations(bot, opts) {
+    if (!opts.expects?.inline)
+        return;
+    if (bot.info?.supports_inline_queries !== false)
+        return; // true, or unknown (no getMe yet)
+    const handle = bot.info?.username ? `@${bot.info.username}` : "this bot";
+    log.warn(`inline mode is OFF for ${handle} — the bot's inline features are dead`);
+    const ids = typeof opts.adminIds === "function"
+        ? await opts.adminIds()
+        : (opts.adminIds ?? []);
+    if (ids.length === 0)
+        return;
+    await notifyAdmins(bot, ids, `⚠️ ${handle}: inline mode is OFF, but this bot's features depend on it.\n` +
+        "Only BotFather can enable it: @BotFather → /setinline (and /setinlinefeedback).");
+}
+//# sourceMappingURL=profile.js.map

package/dist/bot/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../src/bot/profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,GAAG,GAAG,YAAY,CAAC,aAAa,CAAC,CAAC;AAExC,qEAAqE;AACrE,MAAM,QAAQ,GAAG,EAAE,CAAC;AACpB,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,MAAM,SAAS,GAAG,GAAG,CAAC;AAiDtB,oEAAoE;AACpE,SAAS,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AACtB,CAAC;AAED,SAAS,aAAa,CACrB,CAAiC,EACjC,CAAiC;IAEjC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,CAAC,CAAC,KAAK,CACb,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CACV,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CACrE,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CACjB,KAAa,EACb,MAAyB,EACzB,GAAW;IAEX,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpD,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC;YACzB,GAAG,CAAC,KAAK,CACR,GAAG,KAAK,KAAK,IAAI,aAAa,GAAG,qBAAqB,KAAK,OAAO,CAClE,CAAC;YACF,OAAO,IAAI,CAAC;QACb,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,MAAM,SAAS,GAAG,CAAC,IAAwB,EAAE,EAAE,CAC9C,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,GAAe,EACf,IAAuB;IAEvB,MAAM,IAAI,GAAoB,EAAE,CAAC;IAEjC,MAAM,QAAQ,GAAG,CAChB,MAAoB,EACpB,IAA2D,EAC1D,EAAE;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACjC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,wCAAwC;QACnF,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;IACnE,CAAC,CAAC;IAEF,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC1D,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YACzC,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACzD,IAAI,OAAO,CAAC,IAAI,KAAK,KAAK;gBAAE,OAAO;YACnC,MAAM,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC;IACJ,CAAC;IACD,IACC,IAAI,CAAC,WAAW;QAChB,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,EAC3D,CAAC;QACF,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YAChD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YAChE,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK;gBAAE,OAAO;YAC1C,MAAM,GAAG,CAAC,GAAG,CAAC,gBAAgB,CAAC;gBAC9B,WAAW,EAAE,KAAK;gBAClB,GAAG,SAAS,CAAC,IAAI,CAAC;aAClB,CAAC,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,qBAAqB,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;QAC9D,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YAC1C,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACrE,IAAI,OAAO,CAAC,iBAAiB,KAAK,KAAK;gBAAE,OAAO;YAChD,MAAM,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC;gBACnC,iBAAiB,EAAE,KAAK;gBACxB,GAAG,SAAS,CAAC,IAAI,CAAC;aAClB,CAAC,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,eAAe,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACrD,CAAC,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC5C,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YAC7D,IAAI,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC;gBAAE,OAAO;YACzC,MAAM,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACzE,GAAG,CAAC,IAAI,CAAC,kBAAkB,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,GAAG,CAAC,KAAK,CAAC,wBAAwB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9C,GAAG,CAAC,KAAK,CACR,6BAA6B,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CACjE,CACD,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,KAAK,UAAU,iBAAiB,CAC/B,GAAe,EACf,IAAuB;IAEvB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM;QAAE,OAAO;IAClC,IAAI,GAAG,CAAC,IAAI,EAAE,uBAAuB,KAAK,KAAK;QAAE,OAAO,CAAC,kCAAkC;IAE3F,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;IACzE,GAAG,CAAC,IAAI,CACP,0BAA0B,MAAM,uCAAuC,CACvE,CAAC;IACF,MAAM,GAAG,GACR,OAAO,IAAI,CAAC,QAAQ,KAAK,UAAU;QAClC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE;QACvB,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;IAC1B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC7B,MAAM,YAAY,CACjB,GAAyC,EACzC,GAAG,EACH,MAAM,MAAM,+DAA+D;QAC1E,iFAAiF,CAClF,CAAC;AACH,CAAC"}

package/dist/tg-html/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `tg-html` — transform arbitrary (LLM-emitted) HTML into Telegram-compatible
+ * `parse_mode=HTML` with opinionated, consistent spacing.
+ *
+ * Telegram's HTML subset has no headings, lists, or block layout — send it
+ * `<h1>`/`<ul>` and the API rejects the whole message. This module accepts the
+ * HTML a model naturally writes and renders the structure typographically:
+ *
+ *   h1                        → <b><u>…</u></b> + blank line
+ *   h2…h6                     → <b>…</b> + blank line
+ *   p/div/section/article/…   → content + blank line
+ *   ul/ol/li                  → `• ` bullets, blank line after the list
+ *   br                        → newline
+ *   blockquote                → kept (newlines inside preserved), newline after
+ *   b/i/u/s/code/pre/a/…      → kept, attributes filtered to Telegram's allow-list
+ *   spoiler / span.tg-spoiler → <tg-spoiler>
+ *   unknown letter-tags       → dropped, content kept (hallucinated markup)
+ *   stray < >                 → escaped, never eaten
+ *
+ * Zero dependencies, no DOM: a single-pass tokenizer over a small recursive
+ * renderer, safe everywhere (Workers included). Successor of the standalone
+ * `tghtml` package (jsr:@adriangalilea/tghtml, now archived), with its lossy
+ * edge cases fixed: `x<5 and y>10` escapes instead of vanishing, and unknown
+ * tags drop their markup instead of leaking `small…/small` fragments.
+ *
+ * @example
+ * import { transform } from '@adriangalilea/utils/tg-html'
+ *
+ * transform('<h1>Title</h1><ul><li>Point</li></ul>')
+ * // '<b><u>Title</u></b>\n\n• Point'
+ */
+/**
+ * Transform HTML into Telegram-compatible `parse_mode=HTML` with consistent
+ * spacing. Never throws; pathological input degrades to escaped plain text.
+ */
+export declare function transform(html: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/tg-html/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tg-html/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA4PH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAa9C"}

package/dist/tg-html/index.js

@@ -0,0 +1,254 @@
+/**
+ * `tg-html` — transform arbitrary (LLM-emitted) HTML into Telegram-compatible
+ * `parse_mode=HTML` with opinionated, consistent spacing.
+ *
+ * Telegram's HTML subset has no headings, lists, or block layout — send it
+ * `<h1>`/`<ul>` and the API rejects the whole message. This module accepts the
+ * HTML a model naturally writes and renders the structure typographically:
+ *
+ *   h1                        → <b><u>…</u></b> + blank line
+ *   h2…h6                     → <b>…</b> + blank line
+ *   p/div/section/article/…   → content + blank line
+ *   ul/ol/li                  → `• ` bullets, blank line after the list
+ *   br                        → newline
+ *   blockquote                → kept (newlines inside preserved), newline after
+ *   b/i/u/s/code/pre/a/…      → kept, attributes filtered to Telegram's allow-list
+ *   spoiler / span.tg-spoiler → <tg-spoiler>
+ *   unknown letter-tags       → dropped, content kept (hallucinated markup)
+ *   stray < >                 → escaped, never eaten
+ *
+ * Zero dependencies, no DOM: a single-pass tokenizer over a small recursive
+ * renderer, safe everywhere (Workers included). Successor of the standalone
+ * `tghtml` package (jsr:@adriangalilea/tghtml, now archived), with its lossy
+ * edge cases fixed: `x<5 and y>10` escapes instead of vanishing, and unknown
+ * tags drop their markup instead of leaking `small…/small` fragments.
+ *
+ * @example
+ * import { transform } from '@adriangalilea/utils/tg-html'
+ *
+ * transform('<h1>Title</h1><ul><li>Point</li></ul>')
+ * // '<b><u>Title</u></b>\n\n• Point'
+ */
+// Tags Telegram's parse_mode=HTML accepts verbatim.
+const TELEGRAM_TAGS = new Set([
+    "b",
+    "strong",
+    "i",
+    "em",
+    "u",
+    "ins",
+    "s",
+    "strike",
+    "del",
+    "span",
+    "tg-spoiler",
+    "a",
+    "code",
+    "pre",
+    "blockquote",
+    "tg-emoji",
+]);
+// Attributes kept per tag; everything else is dropped.
+const TELEGRAM_ATTRS = {
+    a: ["href"],
+    span: ["class"],
+    blockquote: ["expandable"],
+    code: ["class"],
+    "tg-emoji": ["emoji-id"],
+};
+// Structural tags this module renders typographically (they can't reach Telegram).
+const STRUCTURAL = new Set([
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "p",
+    "div",
+    "section",
+    "article",
+    "header",
+    "footer",
+    "ul",
+    "ol",
+    "li",
+    "br",
+    "spoiler",
+    // Document wrappers a model sometimes emits around its answer; rendered transparent.
+    "html",
+    "head",
+    "body",
+]);
+// Void tags: never expect a closing counterpart.
+const VOID_TAGS = new Set(["br", "meta", "hr", "img", "input"]);
+// A tag token must start with a letter (like real HTML): `<1mb>` or `<5` is text, not markup.
+const TAG_RE = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/?)>/g;
+const ATTR_RE = /([a-zA-Z][a-zA-Z0-9-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+function parseAttrs(raw) {
+    const attrs = {};
+    for (const m of raw.matchAll(ATTR_RE)) {
+        attrs[m[1].toLowerCase()] = m[2] ?? m[3] ?? m[4] ?? "";
+    }
+    return attrs;
+}
+/** Tokenize + tree-build in one pass. Mismatched closers close intervening elements (recovery). */
+function parse(html) {
+    const root = {
+        kind: "element",
+        tag: "#root",
+        attrs: {},
+        children: [],
+    };
+    const stack = [root];
+    let last = 0;
+    const pushText = (text) => {
+        if (text)
+            stack[stack.length - 1].children.push({ kind: "text", text });
+    };
+    for (const m of html.matchAll(TAG_RE)) {
+        pushText(html.slice(last, m.index));
+        last = (m.index ?? 0) + m[0].length;
+        const closing = m[1] === "/";
+        const tag = m[2].toLowerCase();
+        const selfClosing = m[4] === "/" || VOID_TAGS.has(tag);
+        const known = TELEGRAM_TAGS.has(tag) || STRUCTURAL.has(tag);
+        if (!known)
+            continue; // hallucinated markup: drop the tag, keep surrounding content
+        if (closing) {
+            // Close up to the matching open element, if any (recovery for mismatches).
+            for (let at = stack.length - 1; at > 0; at--) {
+                if (stack[at].tag === tag) {
+                    stack.length = at;
+                    break;
+                }
+            }
+            continue;
+        }
+        const el = {
+            kind: "element",
+            tag,
+            attrs: parseAttrs(m[3]),
+            children: [],
+        };
+        stack[stack.length - 1].children.push(el);
+        if (!selfClosing)
+            stack.push(el);
+    }
+    pushText(html.slice(last));
+    return root.children;
+}
+// ─── rendering ──────────────────────────────────────────────────────
+function escapeText(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeAttr(s) {
+    return escapeText(s).replace(/"/g, "&quot;");
+}
+function renderText(text, mode) {
+    const escaped = escapeText(text);
+    if (mode === "verbatim")
+        return escaped;
+    if (mode === "quote") {
+        return escaped
+            .replace(/[ \t]+/g, " ")
+            .replace(/\n[ \t]+/g, "\n")
+            .replace(/[ \t]+\n/g, "\n")
+            .replace(/\n{3,}/g, "\n\n");
+    }
+    return escaped.replace(/\s+/g, " ");
+}
+function renderChildren(el, mode) {
+    let out = "";
+    for (const child of el.children) {
+        out +=
+            child.kind === "text"
+                ? renderText(child.text, mode)
+                : renderElement(child, mode);
+    }
+    return out;
+}
+function keptAttrs(el) {
+    let out = "";
+    for (const name of TELEGRAM_ATTRS[el.tag] ?? []) {
+        if (!(name in el.attrs))
+            continue;
+        let value = el.attrs[name];
+        // Scheme-less links get https; only http(s)/tg pass through untouched.
+        if (el.tag === "a" &&
+            name === "href" &&
+            value &&
+            !/^(https?|tg):/i.test(value)) {
+            value = `https://${value}`;
+        }
+        out += ` ${name}="${escapeAttr(value)}"`;
+    }
+    return out;
+}
+function renderElement(el, mode) {
+    const tag = el.tag;
+    if (tag === "br")
+        return "\n";
+    if (tag === "h1")
+        return `<b><u>${renderChildren(el, "collapse").trim()}</u></b>\n\n`;
+    if (/^h[2-6]$/.test(tag))
+        return `<b>${renderChildren(el, "collapse").trim()}</b>\n\n`;
+    if (tag === "ul" || tag === "ol") {
+        const items = el.children
+            .filter((c) => c.kind === "element" && c.tag === "li")
+            .map((li) => `• ${renderChildren(li, "collapse").trim()}`);
+        return `${items.join("\n")}\n\n`;
+    }
+    if (tag === "li")
+        return `• ${renderChildren(el, "collapse").trim()}\n`;
+    if ([
+        "p",
+        "div",
+        "section",
+        "article",
+        "header",
+        "footer",
+        "html",
+        "head",
+        "body",
+    ].includes(tag)) {
+        return `${renderChildren(el, mode).trim()}\n\n`;
+    }
+    if (tag === "blockquote") {
+        const expandable = "expandable" in el.attrs ? ' expandable=""' : "";
+        return `<blockquote${expandable}>${renderChildren(el, "quote").trim()}</blockquote>\n`;
+    }
+    if (tag === "spoiler")
+        return `<tg-spoiler>${renderChildren(el, "collapse").trim()}</tg-spoiler>`;
+    if (tag === "span") {
+        // Only the spoiler span means anything to Telegram; other spans are transparent.
+        if (el.attrs.class !== "tg-spoiler")
+            return renderChildren(el, mode);
+        return `<span class="tg-spoiler">${renderChildren(el, "collapse").trim()}</span>`;
+    }
+    if (TELEGRAM_TAGS.has(tag)) {
+        // Quote mode applies to a blockquote's DIRECT text only: an inline tag inside it
+        // collapses its own whitespace like anywhere else.
+        const inner = tag === "pre" || tag === "code" ? "verbatim" : "collapse";
+        return `<${tag}${keptAttrs(el)}>${renderChildren(el, inner).trim()}</${tag}>`;
+    }
+    return renderChildren(el, mode);
+}
+/**
+ * Transform HTML into Telegram-compatible `parse_mode=HTML` with consistent
+ * spacing. Never throws; pathological input degrades to escaped plain text.
+ */
+export function transform(html) {
+    if (!html.trim())
+        return "";
+    return parse(html)
+        .map((n) => n.kind === "text"
+        ? renderText(n.text, "collapse")
+        : renderElement(n, "collapse"))
+        .join("")
+        .replace(/\n{3,}/g, "\n\n")
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n +/g, "\n")
+        .trim();
+}
+//# sourceMappingURL=index.js.map

package/dist/tg-html/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "1.2.0",
+	"version": "1.4.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -40,6 +40,10 @@
 			"types": "./dist/say/index.d.ts",
 			"default": "./dist/say/index.js"
 		},
+		"./tg-html": {
+			"types": "./dist/tg-html/index.d.ts",
+			"default": "./dist/tg-html/index.js"
+		},
 		"./bot": {
 			"types": "./dist/bot/index.d.ts",
 			"default": "./dist/bot/index.js"
@@ -115,6 +119,10 @@
 		"./bot/create": {
 			"types": "./dist/bot/create.d.ts",
 			"default": "./dist/bot/create.js"
+		},
+		"./bot/profile": {
+			"types": "./dist/bot/profile.d.ts",
+			"default": "./dist/bot/profile.js"
 		}
 	},
 	"files": [
@@ -137,7 +145,8 @@
 		"ci": "biome ci",
 		"prepublishOnly": "pnpm run build",
 		"test:worker-safe": "pnpm run build && tsx tests/worker-safe-test.ts",
-		"demo:bot": "tsx tests/create-demo.ts"
+		"demo:bot": "tsx tests/create-demo.ts",
+		"test:tg-html": "tsx tests/tg-html-test.ts"
 	},
 	"keywords": [
 		"typescript",