@adriangalilea/utils 2.13.0 → 2.14.0

package/README.md

@@ -524,6 +524,7 @@ Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc.
 | `@adriangalilea/utils/bot/groups` | Group-chat identity as plain functions: `chatIdOf(ctx)` (the chat id on any ctx flavour), `isGroupChat(ctx)` / `isPrivateChat(ctx)`, and `isGroupAdmin(ctx, { chatId?, userId? }?)` — the `getChatMember` creator/administrator check behind every admin-gated group setting (auto-summary toggles, "dismiss" buttons on group welcomes), chat/user defaulted from the ctx. Every reader resolves both gramio spellings — message ctxs carry `chat`, callback ctxs (inline-button taps) only `chatId`/`message.chat` — so the same gate works in handlers and taps; read chat ids via `chatIdOf`, never `ctx.chat?.id`. Takes real gramio ctxs and `MenuCtx` with no cast; a miswired ctx panics, an API rejection fails closed (`false`). Composition over policy: bot-owner override stays at your call site (`ctx.isAdmin \|\| await isGroupAdmin(ctx)`). |
 | `@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), `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/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. |
 | `@adriangalilea/utils/llm` | Multi-provider LLM caller on the Vercel AI SDK — the policy layer the SDK doesn't ship. `createLlm({ providers, health? })` → `.stream(req)` (typed events: `delta` / `reasoning` / `reset` / `tool-call` / `end`) and `.complete(req)`. **Failover:** priority-ordered across OpenAI-compatible, Anthropic-compatible, and OpenRouter endpoints; multiple keys per provider (health tracked per key fingerprint); per-key circuit breaker with exponential cool-down persisted in any KV-shaped `HealthStore`; an attempt that dies after emitting yields `reset` (discard, next candidate regenerates); empty completions count as failures. **Accounting:** tokens summed across billed attempts; `costUsd` is the ACTUAL charge (OpenRouter usage accounting via `providerMetadata`, or a `cost` field on the raw usage frame) — never a price-table estimate. **Knobs:** per-model temperature, maxTokens caps, `disableThinking` mapped to each dialect. **Tools:** AI SDK `tool()` + `toolChoice` pass through (re-exported). Worker-safe; peers: `ai`, `@ai-sdk/openai-compatible`, `@ai-sdk/anthropic`, `@openrouter/ai-sdk-provider`. |

package/dist/bot/urls.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Telegram-message URL + entity parsing, on what the platform ALREADY parsed:
+ * every message arrives with `entities` (bot_command, mention, url, text_link,
+ * …) carrying exact UTF-16 spans — JS strings are UTF-16, so `slice(offset,
+ * offset + length)` is exact. Hand-sniffing `startsWith("/")` or regex-
+ * stripping `@botname` re-derives (worse) what Telegram handed over.
+ *
+ * The load-bearing verb is {@link urlsInMessage}: 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 and rich posts carry). Everything returns the same `Url`
+ * objects as the url module, spans indexing the message text (a text_link's
+ * span is its anchor words), so span-based cutting works uniformly.
+ *
+ * Framework-agnostic by shape: gramio's MessageEntity class satisfies
+ * {@link EntityLike} structurally (type/offset/length/url getters), as does
+ * the raw Bot API object.
+ */
+import { type Url, type UrlsInOptions } from "../universal/url/index.js";
+/** The slice of a Telegram MessageEntity this module reads (raw API object or gramio class alike). */
+export interface EntityLike {
+    type: string;
+    /** Offset in UTF-16 code units — JS string indexing, exactly. */
+    offset: number;
+    length: number;
+    /** For `text_link` only: the hidden URL behind the anchor words. */
+    url?: string;
+}
+/** The slice of a Telegram message this module reads: text or caption, with its entities. */
+export interface MessageLike {
+    text?: string;
+    caption?: string;
+    entities?: readonly EntityLike[];
+    captionEntities?: readonly EntityLike[];
+}
+/** The message's text (or media caption), with the entity set that indexes it. */
+export declare function messageTextAndEntities(message: MessageLike): {
+    text: string;
+    entities: readonly EntityLike[];
+};
+/**
+ * Every URL the message carries, in span order, fully resolved: the visible
+ * text scanned by `urlsIn`, plus each `text_link` entity's hidden URL. A
+ * text_link's `raw` is its visible anchor words and its span covers them, so
+ * cutting link spans out of a message treats hyperlinked words as part of
+ * the link, not as the user's own words. text_link URLs always carry a
+ * scheme, so `requireScheme` never drops them.
+ */
+export declare function urlsInMessage(message: MessageLike, opts?: UrlsInOptions): Url[];
+/** True when the message IS a command: a `bot_command` entity at offset 0 — Telegram's own parse, not `startsWith("/")`. */
+export declare function isCommandMessage(message: MessageLike): boolean;
+/**
+ * The message text with the entity spans `shouldCut` selects replaced by a
+ * space (offsets are honored exactly, so nested/adjacent formatting never
+ * shifts). The predicate receives each entity and its visible slice — e.g.
+ * cut `bot_command`s and mentions of your own bot, keep everything else.
+ */
+export declare function cutEntities(text: string, entities: readonly EntityLike[], shouldCut: (entity: EntityLike, slice: string) => boolean): string;
+//# sourceMappingURL=urls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/bot/urls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,KAAK,GAAG,EAAE,KAAK,aAAa,EAAiB,MAAM,2BAA2B,CAAC;AAExF,sGAAsG;AACtG,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,6FAA6F;AAC7F,MAAM,WAAW,WAAW;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACjC,eAAe,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACxC;AAED,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAI9G;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,GAAG,EAAE,CAe/E;AAED,4HAA4H;AAC5H,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAG9D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,SAAS,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GACvD,MAAM,CASR"}

package/dist/bot/urls.js

@@ -0,0 +1,73 @@
+/**
+ * Telegram-message URL + entity parsing, on what the platform ALREADY parsed:
+ * every message arrives with `entities` (bot_command, mention, url, text_link,
+ * …) carrying exact UTF-16 spans — JS strings are UTF-16, so `slice(offset,
+ * offset + length)` is exact. Hand-sniffing `startsWith("/")` or regex-
+ * stripping `@botname` re-derives (worse) what Telegram handed over.
+ *
+ * The load-bearing verb is {@link urlsInMessage}: 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 and rich posts carry). Everything returns the same `Url`
+ * objects as the url module, spans indexing the message text (a text_link's
+ * span is its anchor words), so span-based cutting works uniformly.
+ *
+ * Framework-agnostic by shape: gramio's MessageEntity class satisfies
+ * {@link EntityLike} structurally (type/offset/length/url getters), as does
+ * the raw Bot API object.
+ */
+import { urlOf, urlsIn } from "../universal/url/index.js";
+/** The message's text (or media caption), with the entity set that indexes it. */
+export function messageTextAndEntities(message) {
+    return message.text !== undefined
+        ? { text: message.text, entities: message.entities ?? [] }
+        : { text: message.caption ?? "", entities: message.captionEntities ?? [] };
+}
+/**
+ * Every URL the message carries, in span order, fully resolved: the visible
+ * text scanned by `urlsIn`, plus each `text_link` entity's hidden URL. A
+ * text_link's `raw` is its visible anchor words and its span covers them, so
+ * cutting link spans out of a message treats hyperlinked words as part of
+ * the link, not as the user's own words. text_link URLs always carry a
+ * scheme, so `requireScheme` never drops them.
+ */
+export function urlsInMessage(message, opts) {
+    const { text, entities } = messageTextAndEntities(message);
+    const out = urlsIn(text, opts);
+    for (const entity of entities) {
+        if (entity.type !== "text_link" || !entity.url)
+            continue;
+        const resolved = urlOf(entity.url, opts);
+        if (!resolved)
+            continue;
+        out.push({
+            ...resolved,
+            raw: text.slice(entity.offset, entity.offset + entity.length),
+            start: entity.offset,
+            end: entity.offset + entity.length,
+        });
+    }
+    return out.sort((a, b) => a.start - b.start);
+}
+/** True when the message IS a command: a `bot_command` entity at offset 0 — Telegram's own parse, not `startsWith("/")`. */
+export function isCommandMessage(message) {
+    const { entities } = messageTextAndEntities(message);
+    return entities.some((e) => e.type === "bot_command" && e.offset === 0);
+}
+/**
+ * The message text with the entity spans `shouldCut` selects replaced by a
+ * space (offsets are honored exactly, so nested/adjacent formatting never
+ * shifts). The predicate receives each entity and its visible slice — e.g.
+ * cut `bot_command`s and mentions of your own bot, keep everything else.
+ */
+export function cutEntities(text, entities, shouldCut) {
+    const doomed = entities
+        .filter((e) => shouldCut(e, text.slice(e.offset, e.offset + e.length)))
+        .sort((a, b) => b.offset - a.offset);
+    let out = text;
+    for (const e of doomed) {
+        out = `${out.slice(0, e.offset)} ${out.slice(e.offset + e.length)}`;
+    }
+    return out;
+}
+//# sourceMappingURL=urls.js.map

package/dist/bot/urls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.js","sourceRoot":"","sources":["../../src/bot/urls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAgC,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAoBxF,kFAAkF;AAClF,MAAM,UAAU,sBAAsB,CAAC,OAAoB;IAC1D,OAAO,OAAO,CAAC,IAAI,KAAK,SAAS;QAChC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,EAAE;QAC1D,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,eAAe,IAAI,EAAE,EAAE,CAAC;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,OAAoB,EAAE,IAAoB;IACvE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/B,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,MAAM,CAAC,GAAG;YAAE,SAAS;QACzD,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,GAAG,CAAC,IAAI,CAAC;YACR,GAAG,QAAQ;YACX,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YAC7D,KAAK,EAAE,MAAM,CAAC,MAAM;YACpB,GAAG,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM;SAClC,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED,4HAA4H;AAC5H,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACpD,MAAM,EAAE,QAAQ,EAAE,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IACrD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAC1B,IAAY,EACZ,QAA+B,EAC/B,SAAyD;IAEzD,MAAM,MAAM,GAAG,QAAQ;SACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;SACtE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACxB,GAAG,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.13.0",
+	"version": "2.14.0",
 	"description": "TypeScript utilities - logger, currency, formatter, GramIO bot plugins, and more",
 	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
@@ -148,6 +148,10 @@
 			"types": "./dist/bot/user.d.ts",
 			"default": "./dist/bot/user.js"
 		},
+		"./bot/urls": {
+			"types": "./dist/bot/urls.d.ts",
+			"default": "./dist/bot/urls.js"
+		},
 		"./llm": {
 			"types": "./dist/llm/index.d.ts",
 			"default": "./dist/llm/index.js"
@@ -191,7 +195,8 @@
 		"test:llm": "tsx tests/llm-live-test.ts",
 		"test:tg-md": "tsx tests/tg-md-test.ts",
 		"test:self-echo": "tsx tests/self-echo-test.ts",
-		"test:url": "tsx tests/url-test.ts"
+		"test:url": "tsx tests/url-test.ts",
+		"test:bot-urls": "tsx tests/bot-urls-test.ts"
 	},
 	"keywords": [
 		"typescript",