@yaebal/broadcast 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,13 @@
+# @yaebal/broadcast
+
+extra params merged into every `sendMessage` (parse_mode, reply_markup, …).
+
+## install
+
+```sh
+pnpm add @yaebal/broadcast
+```
+
+---
+
+part of [**yaebal**](https://github.com/neverlane/yaebal) — a type-safe, runtime-agnostic Telegram Bot API framework. MIT.

package/lib/index.d.ts

@@ -0,0 +1,18 @@
+import type { Api } from "@yaebal/core";
+export interface BroadcastResult {
+    sent: number;
+    failed: number;
+}
+export interface BroadcastOptions {
+    /** Extra params merged into every `sendMessage` (parse_mode, reply_markup, …). */
+    extra?: Record<string, unknown>;
+    /** Called for each chat that failed (blocked the bot, deleted account, …). */
+    onError?: (chatId: number | string, error: unknown) => void;
+}
+/**
+ * Send `text` to many chats, one at a time, counting successes and failures.
+ * Failures (a user blocked the bot, etc.) are swallowed so one bad chat doesn't
+ * abort the run. Pair with `@yaebal/throttle` to stay under Telegram's rate limit.
+ */
+export declare function broadcast(api: Api, chatIds: Array<number | string>, text: string, options?: BroadcastOptions): Promise<BroadcastResult>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAExC,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAChC,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5D;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC9B,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,gBAAqB,GAC5B,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

package/lib/index.js

@@ -0,0 +1,22 @@
+/**
+ * Send `text` to many chats, one at a time, counting successes and failures.
+ * Failures (a user blocked the bot, etc.) are swallowed so one bad chat doesn't
+ * abort the run. Pair with `@yaebal/throttle` to stay under Telegram's rate limit.
+ */
+export async function broadcast(api, chatIds, text, options = {}) {
+    let sent = 0;
+    let failed = 0;
+    for (const chatId of chatIds) {
+        try {
+            // extra first so the per-chat fields always win (extra can't clobber chat_id/text)
+            await api.sendMessage({ ...options.extra, chat_id: chatId, text });
+            sent += 1;
+        }
+        catch (error) {
+            failed += 1;
+            options.onError?.(chatId, error);
+        }
+    }
+    return { sent, failed };
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC9B,GAAQ,EACR,OAA+B,EAC/B,IAAY,EACZ,UAA4B,EAAE;IAE9B,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC;YACJ,mFAAmF;YACnF,MAAM,GAAG,CAAC,WAAW,CAAC,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YACnE,IAAI,IAAI,CAAC,CAAC;QACX,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,CAAC,CAAC;YACZ,OAAO,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAClC,CAAC;IACF,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACzB,CAAC"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { broadcast } from "./index.js";
+function fakeApi(failOn = []) {
+    const sentTo = [];
+    const api = {
+        sendMessage: (params) => {
+            if (failOn.includes(params.chat_id))
+                return Promise.reject(new Error("blocked"));
+            sentTo.push(params.chat_id);
+            return Promise.resolve({ message_id: 1 });
+        },
+    };
+    return { api, sentTo };
+}
+test("broadcast sends to every chat and counts successes", async () => {
+    const { api, sentTo } = fakeApi();
+    const result = await broadcast(api, [1, 2, 3], "hi");
+    assert.deepEqual(result, { sent: 3, failed: 0 });
+    assert.deepEqual(sentTo, [1, 2, 3]);
+});
+test("broadcast survives failures and reports them", async () => {
+    const { api, sentTo } = fakeApi([2]);
+    const failures = [];
+    const result = await broadcast(api, [1, 2, 3], "hi", {
+        onError: (id) => failures.push(id),
+    });
+    assert.deepEqual(result, { sent: 2, failed: 1 });
+    assert.deepEqual(sentTo, [1, 3]); // 2 failed but didn't abort the run
+    assert.deepEqual(failures, [2]);
+});
+test("broadcast merges extra params into every send", async () => {
+    const seen = [];
+    const api = {
+        sendMessage: (p) => {
+            seen.push(p);
+            return Promise.resolve({ message_id: 1 });
+        },
+    };
+    await broadcast(api, [10], "yo", { extra: { parse_mode: "HTML" } });
+    assert.deepEqual(seen, [{ chat_id: 10, text: "yo", parse_mode: "HTML" }]);
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

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

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@yaebal/broadcast",
+  "version": "0.0.1",
+  "description": "yaebal broadcast — send a message to many chats, counting successes and failures.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "broadcast"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/broadcast"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,50 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { broadcast } from "./index.js";
+
+function fakeApi(failOn: Array<number | string> = []) {
+	const sentTo: Array<number | string> = [];
+	const api = {
+		sendMessage: (params: { chat_id: number | string }) => {
+			if (failOn.includes(params.chat_id)) return Promise.reject(new Error("blocked"));
+			sentTo.push(params.chat_id);
+			return Promise.resolve({ message_id: 1 });
+		},
+	} as never;
+
+	return { api, sentTo };
+}
+
+test("broadcast sends to every chat and counts successes", async () => {
+	const { api, sentTo } = fakeApi();
+	const result = await broadcast(api, [1, 2, 3], "hi");
+
+	assert.deepEqual(result, { sent: 3, failed: 0 });
+	assert.deepEqual(sentTo, [1, 2, 3]);
+});
+
+test("broadcast survives failures and reports them", async () => {
+	const { api, sentTo } = fakeApi([2]);
+
+	const failures: Array<number | string> = [];
+	const result = await broadcast(api, [1, 2, 3], "hi", {
+		onError: (id) => failures.push(id),
+	});
+
+	assert.deepEqual(result, { sent: 2, failed: 1 });
+	assert.deepEqual(sentTo, [1, 3]); // 2 failed but didn't abort the run
+	assert.deepEqual(failures, [2]);
+});
+
+test("broadcast merges extra params into every send", async () => {
+	const seen: unknown[] = [];
+	const api = {
+		sendMessage: (p: unknown) => {
+			seen.push(p);
+			return Promise.resolve({ message_id: 1 });
+		},
+	} as never;
+	
+	await broadcast(api, [10], "yo", { extra: { parse_mode: "HTML" } });
+	assert.deepEqual(seen, [{ chat_id: 10, text: "yo", parse_mode: "HTML" }]);
+});

package/src/index.ts

@@ -0,0 +1,41 @@
+import type { Api } from "@yaebal/core";
+
+export interface BroadcastResult {
+	sent: number;
+	failed: number;
+}
+
+export interface BroadcastOptions {
+	/** Extra params merged into every `sendMessage` (parse_mode, reply_markup, …). */
+	extra?: Record<string, unknown>;
+	/** Called for each chat that failed (blocked the bot, deleted account, …). */
+	onError?: (chatId: number | string, error: unknown) => void;
+}
+
+/**
+ * Send `text` to many chats, one at a time, counting successes and failures.
+ * Failures (a user blocked the bot, etc.) are swallowed so one bad chat doesn't
+ * abort the run. Pair with `@yaebal/throttle` to stay under Telegram's rate limit.
+ */
+export async function broadcast(
+	api: Api,
+	chatIds: Array<number | string>,
+	text: string,
+	options: BroadcastOptions = {},
+): Promise<BroadcastResult> {
+	let sent = 0;
+	let failed = 0;
+
+	for (const chatId of chatIds) {
+		try {
+			// extra first so the per-chat fields always win (extra can't clobber chat_id/text)
+			await api.sendMessage({ ...options.extra, chat_id: chatId, text });
+			sent += 1;
+		} catch (error) {
+			failed += 1;
+			options.onError?.(chatId, error);
+		}
+	}
+	
+	return { sent, failed };
+}