@yaebal/media-group 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/media-group
+
+called once per album, with every message in the group.
+
+## install
+
+```sh
+pnpm add @yaebal/media-group
+```
+
+---
+
+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,14 @@
+import type { Context, Message, Plugin } from "@yaebal/core";
+/** called once per album, with every message in the group. */
+export type MediaGroupHandler = (ctx: Context, messages: Message[]) => unknown | Promise<unknown>;
+export interface MediaGroupOptions {
+    /** how long to wait for more album parts before firing. defaults to 200ms. */
+    delayMs?: number;
+}
+/**
+ * telegram delivers an album as separate updates sharing a `media_group_id`.
+ * this buffers them and fires `handler(ctx, messages)` once, after a short
+ * debounce. album parts are consumed — they don't reach other handlers.
+ */
+export declare function mediaGroup(handler: MediaGroupHandler, options?: MediaGroupOptions): Plugin<Context, Record<never, never>>;
+//# 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,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE7D,8DAA8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAElG,MAAM,WAAW,iBAAiB;IACjC,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAQD;;;;GAIG;AACH,wBAAgB,UAAU,CACzB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,iBAAsB,GAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAiCvC"}

package/lib/index.js

@@ -0,0 +1,34 @@
+/**
+ * telegram delivers an album as separate updates sharing a `media_group_id`.
+ * this buffers them and fires `handler(ctx, messages)` once, after a short
+ * debounce. album parts are consumed — they don't reach other handlers.
+ */
+export function mediaGroup(handler, options = {}) {
+    const delayMs = options.delayMs ?? 200;
+    const groups = new Map();
+    const flush = (id) => {
+        const group = groups.get(id);
+        if (!group)
+            return;
+        groups.delete(id);
+        void handler(group.ctx, group.messages);
+    };
+    const plugin = (composer) => composer.use((ctx, next) => {
+        const msg = ctx.message;
+        const id = msg?.media_group_id;
+        if (!msg || id === undefined)
+            return next();
+        const group = groups.get(id);
+        if (group) {
+            group.messages.push(msg);
+            clearTimeout(group.timer);
+            group.timer = setTimeout(() => flush(id), delayMs);
+        }
+        else {
+            groups.set(id, { ctx, messages: [msg], timer: setTimeout(() => flush(id), delayMs) });
+        }
+        // consumed — the album is handled here
+    });
+    return plugin;
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACzB,OAA0B,EAC1B,UAA6B,EAAE;IAE/B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;IAExC,MAAM,KAAK,GAAG,CAAC,EAAU,EAAQ,EAAE;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAClB,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC,CAAC;IAEF,MAAM,MAAM,GAA0C,CAAC,QAAQ,EAAE,EAAE,CAClE,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,OAA8D,CAAC;QAC/E,MAAM,EAAE,GAAG,GAAG,EAAE,cAAc,CAAC;QAE/B,IAAI,CAAC,GAAG,IAAI,EAAE,KAAK,SAAS;YAAE,OAAO,IAAI,EAAE,CAAC;QAE5C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC7B,IAAI,KAAK,EAAE,CAAC;YACX,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAE1B,KAAK,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACP,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACvF,CAAC;QAED,uCAAuC;IACxC,CAAC,CAAC,CAAC;IAEJ,OAAO,MAAM,CAAC;AACf,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,55 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context } from "@yaebal/core";
+import { mediaGroup } from "./index.js";
+const noop = async () => { };
+const entry = (c) => c.toMiddleware();
+const api = {};
+const albumCtx = (groupId, text) => new Context({
+    api,
+    update: {
+        update_id: 1,
+        message: {
+            message_id: 1,
+            date: 0,
+            chat: { id: 1, type: "private" },
+            from: { id: 1, is_bot: false, first_name: "u" },
+            media_group_id: groupId,
+            text,
+        },
+    },
+    updateType: "message",
+});
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+test("album parts are collected into one handler call", async () => {
+    const captured = [];
+    const mw = entry(new Composer().install(mediaGroup((_ctx, messages) => {
+        captured.push(messages);
+    }, { delayMs: 5 })));
+    await mw(albumCtx("g1", "a"), noop);
+    await mw(albumCtx("g1", "b"), noop);
+    await mw(albumCtx("g1", "c"), noop);
+    await wait(25); // past the debounce
+    assert.equal(captured.length, 1); // one album, one call
+    assert.deepEqual(captured[0]?.map((m) => m.text), ["a", "b", "c"]);
+});
+test("messages without a media_group_id pass through", async () => {
+    let through = false;
+    const mw = entry(new Composer().install(mediaGroup(() => { }, { delayMs: 5 })).on("message:text", () => {
+        through = true;
+    }));
+    await mw(albumCtx(undefined, "plain"), noop);
+    assert.equal(through, true);
+});
+test("separate albums fire independently", async () => {
+    const sizes = [];
+    const mw = entry(new Composer().install(mediaGroup((_ctx, messages) => {
+        sizes.push(messages.length);
+    }, { delayMs: 5 })));
+    await mw(albumCtx("a", "1"), noop);
+    await mw(albumCtx("b", "1"), noop);
+    await mw(albumCtx("b", "2"), noop);
+    await wait(25);
+    assert.deepEqual(sizes.sort(), [1, 2]);
+});
+//# 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,48 @@
+{
+  "name": "@yaebal/media-group",
+  "version": "0.0.1",
+  "description": "yaebal media-group plugin — collect album updates into one handler call.",
+  "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",
+    "media-group",
+    "album"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/media-group"
+  },
+  "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,87 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Composer, Context, type Message, type Middleware } from "@yaebal/core";
+import { mediaGroup } from "./index.js";
+
+const noop = async () => {};
+const entry = <C extends Context>(c: Composer<C>) =>
+	c.toMiddleware() as unknown as Middleware<Context>;
+
+const api = {} as never;
+const albumCtx = (groupId: string | undefined, text: string) =>
+	new Context({
+		api,
+		update: {
+			update_id: 1,
+			message: {
+				message_id: 1,
+				date: 0,
+				chat: { id: 1, type: "private" },
+				from: { id: 1, is_bot: false, first_name: "u" },
+				media_group_id: groupId,
+				text,
+			},
+		} as never,
+		updateType: "message",
+	});
+
+const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+test("album parts are collected into one handler call", async () => {
+	const captured: Message[][] = [];
+	const mw = entry(
+		new Composer<Context>().install(
+			mediaGroup(
+				(_ctx, messages) => {
+					captured.push(messages);
+				},
+				{ delayMs: 5 },
+			),
+		),
+	);
+
+	await mw(albumCtx("g1", "a"), noop);
+	await mw(albumCtx("g1", "b"), noop);
+	await mw(albumCtx("g1", "c"), noop);
+	await wait(25); // past the debounce
+
+	assert.equal(captured.length, 1); // one album, one call
+	assert.deepEqual(
+		captured[0]?.map((m) => m.text),
+		["a", "b", "c"],
+	);
+});
+
+test("messages without a media_group_id pass through", async () => {
+	let through = false;
+	const mw = entry(
+		new Composer<Context>().install(mediaGroup(() => {}, { delayMs: 5 })).on("message:text", () => {
+			through = true;
+		}),
+	);
+
+	await mw(albumCtx(undefined, "plain"), noop);
+
+	assert.equal(through, true);
+});
+
+test("separate albums fire independently", async () => {
+	const sizes: number[] = [];
+	const mw = entry(
+		new Composer<Context>().install(
+			mediaGroup(
+				(_ctx, messages) => {
+					sizes.push(messages.length);
+				},
+				{ delayMs: 5 },
+			),
+		),
+	);
+
+	await mw(albumCtx("a", "1"), noop);
+	await mw(albumCtx("b", "1"), noop);
+	await mw(albumCtx("b", "2"), noop);
+	
+	await wait(25);
+	assert.deepEqual(sizes.sort(), [1, 2]);
+});

package/src/index.ts

@@ -0,0 +1,58 @@
+import type { Context, Message, Plugin } from "@yaebal/core";
+
+/** called once per album, with every message in the group. */
+export type MediaGroupHandler = (ctx: Context, messages: Message[]) => unknown | Promise<unknown>;
+
+export interface MediaGroupOptions {
+	/** how long to wait for more album parts before firing. defaults to 200ms. */
+	delayMs?: number;
+}
+
+interface Group {
+	ctx: Context;
+	messages: Message[];
+	timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * telegram delivers an album as separate updates sharing a `media_group_id`.
+ * this buffers them and fires `handler(ctx, messages)` once, after a short
+ * debounce. album parts are consumed — they don't reach other handlers.
+ */
+export function mediaGroup(
+	handler: MediaGroupHandler,
+	options: MediaGroupOptions = {},
+): Plugin<Context, Record<never, never>> {
+	const delayMs = options.delayMs ?? 200;
+	const groups = new Map<string, Group>();
+
+	const flush = (id: string): void => {
+		const group = groups.get(id);
+		if (!group) return;
+
+		groups.delete(id);
+		void handler(group.ctx, group.messages);
+	};
+
+	const plugin: Plugin<Context, Record<never, never>> = (composer) =>
+		composer.use((ctx, next) => {
+			const msg = ctx.message as (Message & { media_group_id?: string }) | undefined;
+			const id = msg?.media_group_id;
+
+			if (!msg || id === undefined) return next();
+
+			const group = groups.get(id);
+			if (group) {
+				group.messages.push(msg);
+				clearTimeout(group.timer);
+				
+				group.timer = setTimeout(() => flush(id), delayMs);
+			} else {
+				groups.set(id, { ctx, messages: [msg], timer: setTimeout(() => flush(id), delayMs) });
+			}
+
+			// consumed — the album is handled here
+		});
+	
+	return plugin;
+}