@adriangalilea/utils 2.22.0 → 2.23.0

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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adriangalilea/utils",
-	"version": "2.22.0",
+	"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": [