@adriangalilea/utils 2.23.0 → 2.24.1

package/README.md

@@ -517,6 +517,7 @@ Telegram's [Threaded Mode](https://telegram.org/blog/threaded-conversations) for
 | `@adriangalilea/utils/bot/language` (picker surface) | The language-picker vocabulary and surfaces, so bots don't fork label lists: `flagFor` / `autonym` / `languageLabel` ("🇪🇸 Español"), `languagePickerItem({ label, codes, isActive, pick })` (the 2-up primary-highlighted MenuItem factory — storage and policy live in your closures), and `addLanguageRows(kb, { codes, pack, active?, activeStyle? })` (the raw-InlineKeyboard twin for onboarding / group-welcome keyboards; `activeStyle: "success"` when primary already marks something else on the keyboard). |
 | `@adriangalilea/utils/bot/user` | `userLabel(u)` — the conditional "[name] [@username] [id]" line every bot re-rolls for admin DMs and logs: `Ada Lovelace (@ada · 42)` / `Ada (42)` / `@ada (42)` / `id 42`, missing pieces drop instead of padding. Reads both gramio spellings (`firstName` / `first_name`); plain text by design. |
 | `@adriangalilea/utils/bot/urls` | Telegram-message URL + entity parsing, on what the platform ALREADY parsed (entities carry exact UTF-16 spans — never `startsWith("/")` or a mention regex). `urlsInMessage(msg)` → the url module's `Url[]`: the visible text scanned by `urlsIn` PLUS `text_link` entities — hyperlinked words whose URL never appears in the text, invisible to any text scanner (what forwarded newsletters carry); a text_link's `raw` is its anchor words and its span covers them, so span-cutting treats linked words as the link. `isCommandMessage(msg)` (a `bot_command` entity at offset 0), `commandToken(msg)` (the leading command without any `@botname` suffix, `/summary@my_bot` → `/summary`; null for ordinary text), `commandAddressee(msg)` (the bot a command is explicitly addressed to, lowercased, null when bare — the group addressing gate: a bare command may belong to any bot in the room, one addressed elsewhere never concerns yours), `cutEntities(text, entities, shouldCut)` (exact span surgery; the predicate sees each visible slice), `messageTextAndEntities(msg)` (text or caption with ITS entity set). Framework-agnostic by shape: gramio's `MessageEntity` class and the raw Bot API object both fit. |
+| `@adriangalilea/utils/bot/announce` | The house announcement (news) template for bot mass messages, first-class: an `Announcement` = banner (`# 📰 <bot> News`), ordered sections (canonical `section.info/features/fixes` with 💬/✨/🐛, free-form allowed), italic closer, `· signature` (middle dot by design, never an em dash). `renderAnnouncement(a)` → the Telegram-markdown subset; `renderAnnouncementBodies({en, es, …})` → per-language bodies for a polyglot broadcast engine ("en" is the required fallback anchor). Pure, zero deps. |
 | `@adriangalilea/utils/bot/updates` | The pending-update queue of a webhook-less bot token, treated as the destroy-on-read resource it is (`getUpdates` with an offset CONFIRMS — destroys — everything below it). `updateQueue({ token, fetch?, apiRoot? })` → `peek({ limit? })` (webhook state + pending count + the queue head, verbatim; sends NO offset so nothing is ever confirmed — repeatable, zero risk), `count()`, `webhookInfo()`, and `drain({ onBatch, limit?, timeoutS?, quietPolls? })` — the one-chance-safe sweep: each raw batch is handed to `onBatch` (persist it somewhere durable) and AWAITED before the offset advances, because the next call is the confirmation; a crash re-delivers the unconfirmed tail on re-run, and the drain ends only after several consecutive silent long-polls, never on the first empty response. A 409 (webhook registered / competing poller) is a typed `SourcedError`, never a silent retry. Plain `fetch`, injectable for tests; no framework. |
 | `@adriangalilea/utils/bot/inline-feedback` | Behavioral tripwire for BotFather's inline feedback probability (gates `chosen_inline_result`; defaults 0%, silently resets on bot transfer and inline-mode toggling, invisible to `getMe`): served-but-never-chosen crosses a threshold → throttled admin DM naming the exact BotFather switch. Storage injected as three ops; never throws into the answer path. |
 | `@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. |

package/dist/bot/announce.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The house announcement ("news") template for bot mass messages, as a first-class structure:
+ * compose an {@link Announcement} once, render it per language, and hand the bodies to a
+ * polyglot broadcast engine. The render targets the common Telegram-markdown subset
+ * (`# heading` → bold, `- ` bullets, `*…*` italics) most bot pipelines already convert to
+ * Telegram HTML — no parse_mode assumptions live here.
+ *
+ * Shape (each section optional, order preserved):
+ *
+ *   # 📰 <banner>
+ *
+ *   💬 Info
+ *   - …
+ *
+ *   ✨ New Features
+ *   - …
+ *
+ *   🐛 Fixes
+ *   - …
+ *
+ *   _<closer>_
+ *
+ *   · <signature>
+ *
+ * The signature separator is a middle dot by design — never an em dash.
+ */
+export interface AnnouncementSection {
+    /** Leading emoji for the section title, e.g. "💬". */
+    emoji: string;
+    /** Section title, e.g. "Info". */
+    title: string;
+    /** Bulleted items, one line each. */
+    items: string[];
+}
+export interface Announcement {
+    /** Banner line, e.g. "theSummaryBot News". Rendered as `# 📰 <banner>`. */
+    banner: string;
+    sections: AnnouncementSection[];
+    /** Italic closing line, e.g. "Questions? Feedback? Feel free to reach out!". */
+    closer?: string;
+    /** Attribution, e.g. "@adriangalilea". Rendered as `· <signature>`. */
+    signature?: string;
+}
+/** The three canonical sections, so every announcement wears the same iconography. */
+export declare const section: {
+    info: (items: string[], title?: string) => AnnouncementSection;
+    features: (items: string[], title?: string) => AnnouncementSection;
+    fixes: (items: string[], title?: string) => AnnouncementSection;
+};
+/** Render one language's announcement to the Telegram-markdown subset. */
+export declare function renderAnnouncement(a: Announcement): string;
+/**
+ * Per-language bodies for a polyglot broadcast: language code → rendered body. "en" is the
+ * required fallback anchor — an engine resolves each recipient's language and falls back to it.
+ */
+export type AnnouncementBodies = Record<string, string>;
+/** Render a per-language map of announcements into broadcast bodies. Throws without "en". */
+export declare function renderAnnouncementBodies(byLanguage: Record<string, Announcement>): AnnouncementBodies;
+//# sourceMappingURL=announce.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"announce.d.ts","sourceRoot":"","sources":["../../src/bot/announce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,MAAM,WAAW,mBAAmB;IACnC,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,KAAK,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC5B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,eAAO,MAAM,OAAO;kBACL,MAAM,EAAE,qBAAmB,mBAAmB;sBAC1C,MAAM,EAAE,qBAA2B,mBAAmB;mBACzD,MAAM,EAAE,qBAAoB,mBAAmB;CAC9D,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAU1D;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAExD,6FAA6F;AAC7F,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,kBAAkB,CAKrG"}

package/dist/bot/announce.js

@@ -0,0 +1,57 @@
+/**
+ * The house announcement ("news") template for bot mass messages, as a first-class structure:
+ * compose an {@link Announcement} once, render it per language, and hand the bodies to a
+ * polyglot broadcast engine. The render targets the common Telegram-markdown subset
+ * (`# heading` → bold, `- ` bullets, `*…*` italics) most bot pipelines already convert to
+ * Telegram HTML — no parse_mode assumptions live here.
+ *
+ * Shape (each section optional, order preserved):
+ *
+ *   # 📰 <banner>
+ *
+ *   💬 Info
+ *   - …
+ *
+ *   ✨ New Features
+ *   - …
+ *
+ *   🐛 Fixes
+ *   - …
+ *
+ *   _<closer>_
+ *
+ *   · <signature>
+ *
+ * The signature separator is a middle dot by design — never an em dash.
+ */
+/** The three canonical sections, so every announcement wears the same iconography. */
+export const section = {
+    info: (items, title = "Info") => ({ emoji: "💬", title, items }),
+    features: (items, title = "New Features") => ({ emoji: "✨", title, items }),
+    fixes: (items, title = "Fixes") => ({ emoji: "🐛", title, items }),
+};
+/** Render one language's announcement to the Telegram-markdown subset. */
+export function renderAnnouncement(a) {
+    const blocks = [`# 📰 ${a.banner}`];
+    for (const s of a.sections) {
+        if (s.items.length === 0)
+            continue;
+        blocks.push(`${s.emoji} **${s.title}**`);
+        blocks.push(s.items.map((i) => `- ${i}`).join("\n"));
+    }
+    if (a.closer)
+        blocks.push(`*${a.closer}*`);
+    if (a.signature)
+        blocks.push(`· ${a.signature}`);
+    return blocks.join("\n\n");
+}
+/** Render a per-language map of announcements into broadcast bodies. Throws without "en". */
+export function renderAnnouncementBodies(byLanguage) {
+    if (!byLanguage.en)
+        throw new Error("announcement bodies need an 'en' fallback");
+    const bodies = {};
+    for (const [lang, a] of Object.entries(byLanguage))
+        bodies[lang] = renderAnnouncement(a);
+    return bodies;
+}
+//# sourceMappingURL=announce.js.map

package/dist/bot/announce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"announce.js","sourceRoot":"","sources":["../../src/bot/announce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAqBH,sFAAsF;AACtF,MAAM,CAAC,MAAM,OAAO,GAAG;IACtB,IAAI,EAAE,CAAC,KAAe,EAAE,KAAK,GAAG,MAAM,EAAuB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC/F,QAAQ,EAAE,CAAC,KAAe,EAAE,KAAK,GAAG,cAAc,EAAuB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC1G,KAAK,EAAE,CAAC,KAAe,EAAE,KAAK,GAAG,OAAO,EAAuB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;CACjG,CAAC;AAEF,0EAA0E;AAC1E,MAAM,UAAU,kBAAkB,CAAC,CAAe;IACjD,MAAM,MAAM,GAAa,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,CAAC,MAAM;QAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,CAAC,SAAS;QAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAQD,6FAA6F;AAC7F,MAAM,UAAU,wBAAwB,CAAC,UAAwC;IAChF,IAAI,CAAC,UAAU,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACjF,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;QAAE,MAAM,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC;IACzF,OAAO,MAAM,CAAC;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.23.0",
+	"version": "2.24.1",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -156,6 +156,10 @@
 			"types": "./dist/bot/urls.d.ts",
 			"default": "./dist/bot/urls.js"
 		},
+		"./bot/announce": {
+			"types": "./dist/bot/announce.d.ts",
+			"default": "./dist/bot/announce.js"
+		},
 		"./bot/updates": {
 			"types": "./dist/bot/updates.d.ts",
 			"default": "./dist/bot/updates.js"
@@ -210,6 +214,7 @@
 		"test:url": "tsx tests/url-test.ts",
 		"test:bot-urls": "tsx tests/bot-urls-test.ts",
 		"test:bot-updates": "tsx tests/bot-updates-test.ts",
+		"test:bot-announce": "tsx tests/bot-announce-test.ts",
 		"test:reactions": "tsx tests/reactions-test.ts"
 	},
 	"keywords": [