@adriangalilea/utils 2.21.1 → 2.23.0

package/README.md

@@ -497,17 +497,9 @@ Cloudflare is one adapter, not the architecture: `bot/worker` and `bot/storage-d
 - **Forget actually forgets.** `personalData.onForget` runs inside the same try as the session delete: your message logs/metrics/credit rows get wiped too, or the user is told it failed — never a partial erasure reading as success.
 - **The composer owns instance wiring.** Features still compose manually (below) when you need full control, but every "same instance" contract has one home.
 
-#### Threaded Mode — pin the `@gramio/contexts` fork
+#### Threaded Mode
 
-Telegram added [Threaded Mode](https://telegram.org/blog/threaded-conversations) for private chats (BotFather → Bot Settings → Threaded Mode). gramio's `SendMixin` skips auto-threading there, and `CallbackQueryContext` doesn't expose `threadId` at all. Fixes [PR'd upstream](https://github.com/gramiojs/contexts/pull/4); until merged, pin the fork in **your bot project's** workspace root (pnpm only honors overrides at the root, not transitively — and pnpm ≥11 reads them from `pnpm-workspace.yaml`, not `package.json`):
-
-```yaml
-# pnpm-workspace.yaml
-overrides:
-  "@gramio/contexts": "github:adriangalilea/contexts#local-build/auto-thread-private-chat-threaded-mode"
-```
-
-Then `pnpm install`. Every `ctx.send` / `ctx.sendDocument` / `ctx.reply` / etc. — including from callback handlers — will auto-forward `message_thread_id` and stay in the thread the message came from. If you don't use Threaded Mode, skip this.
+Telegram's [Threaded Mode](https://telegram.org/blog/threaded-conversations) for private chats (BotFather → Bot Settings → Threaded Mode) auto-threads out of the box: `@gramio/contexts` ≥0.9 (what gramio ≥0.12 resolves) forwards `message_thread_id` on every `ctx.send` / `ctx.sendDocument` / `ctx.reply` — including from callback handlers, which carry `threadId` too. No fork, no override.
 
 **Runs on Cloudflare Workers / bun / anywhere.** Every bot subpath below is import-safe off Node — no filesystem access, no `node:*` modules, no import-time side effects anywhere in its graph — **except `bot/kit`**, which deliberately owns the Node-only pieces (process signal handling in `gracefulStart`, kev-backed env reading in `adminContext`). `pnpm test:worker-safe` walks every graph and screams on regression.
 
@@ -524,7 +516,8 @@ 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/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/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. |
 | `@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/updates.d.ts

@@ -0,0 +1,53 @@
+/** A raw Bot API update. Only `update_id` is load-bearing here; everything else passes through. */
+export interface TelegramUpdate {
+    update_id: number;
+    [key: string]: unknown;
+}
+export interface QueuePeek {
+    /** The registered webhook URL, or null when the token polls (getUpdates works). */
+    webhookUrl: string | null;
+    /** Updates waiting server-side (`getWebhookInfo.pending_update_count`). */
+    pending: number;
+    /** The first updates in the queue, verbatim. Empty when a webhook is registered (polling
+     *  would 409) — the count above still tells the story. */
+    head: TelegramUpdate[];
+}
+export interface DrainResult {
+    drained: number;
+    batches: number;
+    lastUpdateId?: number;
+}
+export interface UpdateQueueOptions {
+    token: string;
+    /** Transport override for tests. Defaults to global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /** Bot API origin override (local Bot API servers). */
+    apiRoot?: string;
+}
+/** Peek/drain/count over one bot token's pending-update queue. See the module doc for the
+ *  destroy-on-read contract each verb upholds. */
+export declare function updateQueue(options: UpdateQueueOptions): {
+    /** Raw `getWebhookInfo`. */
+    webhookInfo(): Promise<Record<string, unknown>>;
+    /** Updates waiting server-side, without touching any of them. */
+    count(): Promise<number>;
+    /** Non-destructive look: webhook state, pending count, and the first `limit` updates,
+     *  verbatim. Confirms NOTHING — repeat as often as you like. */
+    peek({ limit }?: {
+        limit?: number;
+    }): Promise<QueuePeek>;
+    /**
+     * Drain the queue, one-chance-safe. `onBatch` receives each raw batch and is AWAITED
+     * before the offset advances — persist there, because the next `getUpdates` call is the
+     * confirmation that destroys the batch server-side. An `onBatch` throw aborts the drain
+     * with nothing confirmed beyond what `onBatch` already accepted; re-running resumes at
+     * the unconfirmed tail. Ends after `quietPolls` consecutive empty long-polls.
+     */
+    drain({ onBatch, limit, timeoutS, quietPolls, }: {
+        onBatch: (updates: TelegramUpdate[]) => void | Promise<void>;
+        limit?: number;
+        timeoutS?: number;
+        quietPolls?: number;
+    }): Promise<DrainResult>;
+};
+//# sourceMappingURL=updates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"updates.d.ts","sourceRoot":"","sources":["../../src/bot/updates.ts"],"names":[],"mappings":"AAqBA,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACzB,mFAAmF;IACnF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;8DAC0D;IAC1D,IAAI,EAAE,cAAc,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;kDACkD;AAClD,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB;IA0BrD,4BAA4B;mBACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI/C,iEAAiE;aAClD,OAAO,CAAC,MAAM,CAAC;IAK9B;oEACgE;qBACtC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAQ,OAAO,CAAC,SAAS,CAAC;IAQtE;;;;;;OAMG;qDAMA;QACF,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,WAAW,CAAC;EAsBzB"}

package/dist/bot/updates.js

@@ -0,0 +1,94 @@
+/**
+ * The pending-update queue of a webhook-less bot token, handled with the respect a
+ * destroy-on-read resource deserves. Telegram's `getUpdates` CONFIRMS (discards) every update
+ * older than the offset it is called with — reading is destructive, and a queue drained
+ * carelessly is gone forever. Two safety properties are the whole point:
+ *
+ *   PEEK is free. `getUpdates` WITHOUT an offset confirms nothing: webhook state, the pending
+ *   count, and the head of the queue are all inspectable, repeatably, at zero risk.
+ *
+ *   DRAIN is write-before-confirm. Each raw batch is handed to the caller's `onBatch` (persist
+ *   it there — disk, db, anywhere durable) and AWAITED before the next `getUpdates` call
+ *   advances the offset, because that next call IS the confirmation. A crash mid-drain loses
+ *   nothing: re-run, and the unconfirmed tail re-delivers. The drain ends only after the queue
+ *   stays silent across several consecutive long-polls, never on the first empty response.
+ *
+ * Framework-free: plain `fetch` against the Bot API, injectable for tests. A 409 means the
+ * token has a webhook registered or another poller is competing — surfaced as a typed error,
+ * never retried silently.
+ */
+import { SourcedError } from "../offensive.js";
+/** Peek/drain/count over one bot token's pending-update queue. See the module doc for the
+ *  destroy-on-read contract each verb upholds. */
+export function updateQueue(options) {
+    const doFetch = options.fetch ?? globalThis.fetch;
+    const root = options.apiRoot ?? "https://api.telegram.org";
+    const call = async (method, params) => {
+        const res = await doFetch(`${root}/bot${options.token}/${method}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(params ?? {}),
+        });
+        const body = (await res.json());
+        if (!body.ok) {
+            throw new SourcedError({
+                source: "telegram",
+                operation: method,
+                message: body.error_code === 409
+                    ? `${body.description ?? "409"} (a webhook is registered, or another poller is competing)`
+                    : (body.description ?? "unknown error"),
+                status: body.error_code ?? res.status,
+            });
+        }
+        return body.result;
+    };
+    return {
+        /** Raw `getWebhookInfo`. */
+        webhookInfo() {
+            return call("getWebhookInfo");
+        },
+        /** Updates waiting server-side, without touching any of them. */
+        async count() {
+            const info = await call("getWebhookInfo");
+            return info.pending_update_count ?? 0;
+        },
+        /** Non-destructive look: webhook state, pending count, and the first `limit` updates,
+         *  verbatim. Confirms NOTHING — repeat as often as you like. */
+        async peek({ limit = 1 } = {}) {
+            const info = await call("getWebhookInfo");
+            const webhookUrl = info.url ? info.url : null;
+            // With a webhook registered getUpdates would 409; the count already tells the story.
+            const head = webhookUrl ? [] : await call("getUpdates", { limit, timeout: 0 });
+            return { webhookUrl, pending: info.pending_update_count ?? 0, head };
+        },
+        /**
+         * Drain the queue, one-chance-safe. `onBatch` receives each raw batch and is AWAITED
+         * before the offset advances — persist there, because the next `getUpdates` call is the
+         * confirmation that destroys the batch server-side. An `onBatch` throw aborts the drain
+         * with nothing confirmed beyond what `onBatch` already accepted; re-running resumes at
+         * the unconfirmed tail. Ends after `quietPolls` consecutive empty long-polls.
+         */
+        async drain({ onBatch, limit = 100, timeoutS = 10, quietPolls = 3, }) {
+            let offset;
+            let drained = 0;
+            let batches = 0;
+            let lastUpdateId;
+            let quiet = 0;
+            while (quiet < quietPolls) {
+                const batch = await call("getUpdates", { offset, limit, timeout: timeoutS });
+                if (batch.length === 0) {
+                    quiet += 1;
+                    continue;
+                }
+                quiet = 0;
+                await onBatch(batch); // persist FIRST…
+                lastUpdateId = batch[batch.length - 1].update_id;
+                offset = lastUpdateId + 1; // …the NEXT call confirms
+                drained += batch.length;
+                batches += 1;
+            }
+            return { drained, batches, lastUpdateId };
+        },
+    };
+}
+//# sourceMappingURL=updates.js.map

package/dist/bot/updates.js.map

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

package/dist/bot/urls.d.ts

@@ -56,6 +56,14 @@ export declare function messageTextAndEntities(message: MessageLike): {
 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 visible command token of a leading `bot_command` entity, without any `@botname` suffix
+ *  (`/summary@my_bot …` → `/summary`). Null for ordinary text. */
+export declare function commandToken(message: MessageLike): string | null;
+/** The bot a leading command is explicitly addressed to (`/cmd@BotName` → `botname`), or null for
+ *  a bare `/cmd`. Lowercased — Telegram usernames are case-insensitive. This is the addressing
+ *  gate for command replies in groups: a bare command may belong to any bot in the room, and one
+ *  addressed elsewhere never concerns yours — answering it is spam. */
+export declare function commandAddressee(message: MessageLike): string | null;
 /**
  * The message text with the entity spans `shouldCut` selects replaced by a
  * space (offsets are honored exactly, so nested/adjacent formatting never

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

@@ -1 +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;+FAC+F;AAC/F,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;IACxC,kBAAkB,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,oBAAoB,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,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,CA0B/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"}
+{"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;+FAC+F;AAC/F,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;IACxC,kBAAkB,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,oBAAoB,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,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,CA0B/E;AAED,4HAA4H;AAC5H,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAG9D;AAED;kEACkE;AAClE,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAMhE;AAED;;;uEAGuE;AACvE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAMpE;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

@@ -65,6 +65,28 @@ export function isCommandMessage(message) {
     const { entities } = messageTextAndEntities(message);
     return entities.some((e) => e.type === "bot_command" && e.offset === 0);
 }
+/** The visible command token of a leading `bot_command` entity, without any `@botname` suffix
+ *  (`/summary@my_bot …` → `/summary`). Null for ordinary text. */
+export function commandToken(message) {
+    const { text, entities } = messageTextAndEntities(message);
+    const entity = entities.find((e) => e.type === "bot_command" && e.offset === 0);
+    if (!entity)
+        return null;
+    const token = text.slice(0, entity.length).split("@", 1)[0];
+    return token || "/?";
+}
+/** The bot a leading command is explicitly addressed to (`/cmd@BotName` → `botname`), or null for
+ *  a bare `/cmd`. Lowercased — Telegram usernames are case-insensitive. This is the addressing
+ *  gate for command replies in groups: a bare command may belong to any bot in the room, and one
+ *  addressed elsewhere never concerns yours — answering it is spam. */
+export function commandAddressee(message) {
+    const { text, entities } = messageTextAndEntities(message);
+    const entity = entities.find((e) => e.type === "bot_command" && e.offset === 0);
+    if (!entity)
+        return null;
+    const addressee = text.slice(0, entity.length).split("@", 2)[1];
+    return addressee ? addressee.toLowerCase() : null;
+}
 /**
  * The message text with the entity spans `shouldCut` selects replaced by a
  * space (offsets are honored exactly, so nested/adjacent formatting never

package/dist/bot/urls.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.21.1",
+	"version": "2.23.0",
 	"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/updates": {
+			"types": "./dist/bot/updates.d.ts",
+			"default": "./dist/bot/updates.js"
+		},
 		"./bot/reactions": {
 			"types": "./dist/bot/reactions.d.ts",
 			"default": "./dist/bot/reactions.js"
@@ -205,6 +209,7 @@
 		"test:self-echo": "tsx tests/self-echo-test.ts",
 		"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:reactions": "tsx tests/reactions-test.ts"
 	},
 	"keywords": [