grammy-media-groups 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2023 grammyjs
+
+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,130 @@
+# Media Groups Storage Plugin for grammY
+
+A [grammY](https://grammy.dev/) plugin that stores media group messages using
+the [storages](https://github.com/grammyjs/storages) protocol. It collects all
+messages that share the same `media_group_id` from both incoming updates and
+outgoing API responses, and lets you retrieve the full group at any time.
+
+## Features
+
+- **Middleware** — automatically stores every incoming message that has a
+  `media_group_id`.
+- **Transformer** — intercepts Telegram API responses (`sendMediaGroup`,
+  `forwardMessage`, `editMessageMedia`, `editMessageCaption`,
+  `editMessageReplyMarkup`) and stores returned messages.
+- **Context hydration** — adds `ctx.mediaGroups.getForMsg()` to fetch the
+  current message's media group.
+- **Reply/pinned helpers** — `ctx.mediaGroups.getForReply()` and
+  `ctx.mediaGroups.getForPinned()` for sub-messages.
+- **Programmatic access** — the returned composer exposes
+  `getMediaGroup(mediaGroupId)` for use outside of middleware.
+- **Manual mode** — pass `{ autoStore: false }` to disable automatic storing
+  and use `ctx.mediaGroups.store(message)` for full control.
+- **Delete** — `ctx.mediaGroups.delete(mediaGroupId)` or
+  `mg.deleteMediaGroup(mediaGroupId)` removes a media group from storage.
+
+## Installation
+
+### Node.js
+
+```bash
+npm install github:PonomareVlad/grammy-media-groups
+```
+
+### Deno
+
+```typescript
+import {
+    mediaGroups,
+    type MediaGroupsFlavor,
+} from "https://raw.githubusercontent.com/PonomareVlad/grammy-media-groups/main/src/mod.ts";
+```
+
+## Usage
+
+```typescript
+import { Bot, Context, InputMediaBuilder } from "grammy";
+import { mediaGroups, type MediaGroupsFlavor } from "@grammyjs/media-groups";
+
+type MyContext = Context & MediaGroupsFlavor;
+
+const bot = new Bot<MyContext>("<your-bot-token>");
+
+// Uses MemorySessionStorage by default — pass a custom adapter for persistence
+const mg = mediaGroups();
+bot.use(mg);
+
+// Install transformer for outgoing API responses
+bot.api.config.use(mg.transformer);
+
+// Retrieve the media group of the current message
+bot.on("message", async (ctx) => {
+    const group = await ctx.mediaGroups.getForMsg();
+    if (group) {
+        console.log(`Media group has ${group.length} messages`);
+    }
+});
+
+// Reply to an album message with /album to resend the full media group
+bot.command("album", async (ctx) => {
+    const group = await ctx.mediaGroups.getForReply();
+    if (group) {
+        await ctx.replyWithMediaGroup(
+            group
+                .map((msg) => {
+                    const opts = {
+                        caption: msg.caption,
+                        caption_entities: msg.caption_entities,
+                    };
+                    switch (true) {
+                        case "photo" in msg: {
+                            const id = msg.photo?.at(-1)?.file_id;
+                            return InputMediaBuilder.photo(id, opts);
+                        }
+                        case "video" in msg: {
+                            const id = msg.video?.file_id;
+                            return InputMediaBuilder.video(id, opts);
+                        }
+                        case "document" in msg: {
+                            const id = msg.document?.file_id;
+                            return InputMediaBuilder.document(id, opts);
+                        }
+                    }
+                })
+                .filter(Boolean),
+        );
+    }
+});
+
+// Programmatic access outside middleware
+const messages = await mg.getMediaGroup("some-media-group-id");
+```
+
+### Manual Mode
+
+To disable automatic storing, pass `{ autoStore: false }`. This gives you full
+control over which messages get stored via `ctx.mediaGroups.store()`:
+
+```typescript
+const mg = mediaGroups(undefined, { autoStore: false });
+bot.use(mg);
+
+bot.on("message", async (ctx) => {
+    // Only store messages you care about
+    if (ctx.msg.media_group_id) {
+        await ctx.mediaGroups.store(ctx.msg);
+    }
+
+    // You can also manually store reply_to_message
+    const reply = ctx.msg.reply_to_message;
+    if (reply?.media_group_id) {
+        await ctx.mediaGroups.store(reply);
+    }
+
+    // Delete a media group when no longer needed
+    // await ctx.mediaGroups.delete("some-media-group-id");
+});
+
+// Delete from outside middleware
+// await mg.deleteMediaGroup("some-media-group-id");
+```

package/out/deps.node.d.ts

@@ -0,0 +1,2 @@
+export { Api, Composer, Context, MemorySessionStorage, type StorageAdapter, type Transformer, } from "grammy";
+export type { Message, UserFromGetMe } from "grammy/types";

package/out/deps.node.js

@@ -0,0 +1 @@
+export { Api, Composer, Context, MemorySessionStorage, } from "grammy";

package/out/mod.d.ts

@@ -0,0 +1,180 @@
+import type { Message } from "./deps.node.js";
+import { Composer, Context, type StorageAdapter, type Transformer } from "./deps.node.js";
+export { MEDIA_GROUP_METHODS, storeMessages } from "./storage.js";
+/**
+ * Options for the media groups plugin.
+ */
+export interface MediaGroupsOptions {
+    /**
+     * When `true` (default), the middleware automatically stores every
+     * incoming message that has a `media_group_id` (including
+     * `reply_to_message` and `pinned_message`).
+     *
+     * Set to `false` to disable automatic storing. In that case use
+     * `ctx.mediaGroups.store(message)` to store messages manually.
+     */
+    autoStore?: boolean;
+}
+/**
+ * Flavor for context that adds media group methods.
+ */
+export type MediaGroupsFlavor = {
+    /**
+     * Namespace of the `media-groups` plugin
+     */
+    mediaGroups: {
+        /**
+         * Gets all messages belonging to the current message's media group.
+         * Returns `undefined` if the current message is not part of a media group.
+         */
+        getForMsg: () => Promise<Message[] | undefined>;
+        /**
+         * Gets the media group of the message being replied to.
+         * Returns `undefined` if there is no reply or it is not part of a media group.
+         */
+        getForReply: () => Promise<Message[] | undefined>;
+        /**
+         * Gets the media group of the pinned message.
+         * Returns `undefined` if there is no pinned message or it is not part of a media group.
+         */
+        getForPinned: () => Promise<Message[] | undefined>;
+        /**
+         * Manually stores a message in its media group.
+         * The message must have a `media_group_id` to be stored.
+         *
+         * @param message The message to store
+         */
+        store: (message: Message) => Promise<void>;
+        /**
+         * Deletes a media group from storage by its ID.
+         *
+         * @param mediaGroupId The media group ID to delete
+         */
+        delete: (mediaGroupId: string) => Promise<void>;
+    };
+};
+type MediaGroupsContext = Context & MediaGroupsFlavor;
+/**
+ * Creates a transformer that intercepts outgoing API responses and
+ * stores returned messages containing `media_group_id`.
+ *
+ * Install it manually on your bot's API:
+ *
+ * ```typescript
+ * bot.api.config.use(mediaGroupTransformer(adapter));
+ * ```
+ *
+ * @param adapter Storage adapter for persisting media group data
+ * @returns An API transformer
+ */
+export declare function mediaGroupTransformer(adapter: StorageAdapter<Message[]>): Transformer<any>;
+/**
+ * Creates middleware that collects media group messages from incoming
+ * updates and hydrates the context with methods to retrieve stored
+ * media groups.
+ *
+ * @param adapter Storage adapter for persisting media group data (defaults to `MemorySessionStorage`)
+ * @param options Plugin options
+ * @returns A composer with middleware installed
+ *
+ * @example
+ * ```typescript
+ * import { Bot, Context, InputMediaBuilder } from "grammy";
+ * import {
+ *     type MediaGroupsFlavor,
+ *     mediaGroups,
+ * } from "@grammyjs/media-groups";
+ *
+ * type MyContext = Context & MediaGroupsFlavor;
+ *
+ * const bot = new Bot<MyContext>("<token>");
+ *
+ * // Uses MemorySessionStorage by default
+ * const mg = mediaGroups();
+ * bot.use(mg);
+ *
+ * // Install transformer for outgoing API responses
+ * bot.api.config.use(mg.transformer);
+ *
+ * // Programmatic access
+ * const messages = await mg.getMediaGroup("some-media-group-id");
+ *
+ * // In a command handler replying to a media group message
+ * bot.command("album", async (ctx) => {
+ *     const group = await ctx.mediaGroups.getForReply();
+ *     if (group) {
+ *         await ctx.replyWithMediaGroup(
+ *             group
+ *                 .map((msg) => {
+ *                     const opts = {
+ *                         caption: msg.caption,
+ *                         caption_entities: msg.caption_entities,
+ *                     };
+ *                     switch (true) {
+ *                         case "photo" in msg: {
+ *                             const id = msg.photo?.at(-1)?.file_id;
+ *                             return InputMediaBuilder.photo(id, opts);
+ *                         }
+ *                         case "video" in msg: {
+ *                             const id = msg.video?.file_id;
+ *                             return InputMediaBuilder.video(id, opts);
+ *                         }
+ *                         case "document" in msg: {
+ *                             const id = msg.document?.file_id;
+ *                             return InputMediaBuilder.document(id, opts);
+ *                         }
+ *                     }
+ *                 })
+ *                 .filter(Boolean),
+ *         );
+ *     }
+ * });
+ *
+ * // Access media group of current message via namespace
+ * bot.on("message", async (ctx) => {
+ *     const group = await ctx.mediaGroups.getForMsg();
+ *     if (group) console.log(`Album has ${group.length} items`);
+ * });
+ * ```
+ *
+ * @example Manual mode — disable automatic storing and use `ctx.mediaGroups.store()` instead:
+ * ```typescript
+ * const mg = mediaGroups(undefined, { autoStore: false });
+ * bot.use(mg);
+ *
+ * bot.on("message", async (ctx) => {
+ *     if (ctx.msg.media_group_id) {
+ *         await ctx.mediaGroups.store(ctx.msg);
+ *     }
+ * });
+ * ```
+ *
+ * @example Deleting a media group from storage:
+ * ```typescript
+ * // From within middleware
+ * await ctx.mediaGroups.delete("some-media-group-id");
+ *
+ * // From outside middleware
+ * await mg.deleteMediaGroup("some-media-group-id");
+ * ```
+ */
+export declare function mediaGroups(adapter?: StorageAdapter<Message[]>, options?: MediaGroupsOptions): Composer<MediaGroupsContext> & {
+    /** The storage adapter used by the plugin. */
+    adapter: StorageAdapter<Message[]>;
+    /** Pre-built API transformer. Install via `bot.api.config.use(mg.transformer)`. */
+    transformer: Transformer<any>;
+    /**
+     * Fetches a media group by its ID from storage.
+     *
+     * @param mediaGroupId The media group ID to look up
+     * @returns Array of messages in the media group, or `undefined` if not found
+     */
+    getMediaGroup: (mediaGroupId: string) => Promise<Message[] | undefined>;
+    /**
+     * Deletes a media group from storage by its ID.
+     *
+     * @param mediaGroupId The media group ID to delete
+     */
+    deleteMediaGroup: (mediaGroupId: string) => Promise<void>;
+};
+export default mediaGroups;

package/out/mod.js

@@ -0,0 +1,165 @@
+import { Composer, MemorySessionStorage, } from "./deps.node.js";
+import { MEDIA_GROUP_METHODS, storeMessages } from "./storage.js";
+export { MEDIA_GROUP_METHODS, storeMessages } from "./storage.js";
+/**
+ * Creates a transformer that intercepts outgoing API responses and
+ * stores returned messages containing `media_group_id`.
+ *
+ * Install it manually on your bot's API:
+ *
+ * ```typescript
+ * bot.api.config.use(mediaGroupTransformer(adapter));
+ * ```
+ *
+ * @param adapter Storage adapter for persisting media group data
+ * @returns An API transformer
+ */
+export function mediaGroupTransformer(adapter) {
+    return async (prev, method, payload, signal) => {
+        const res = await prev(method, payload, signal);
+        const extractor = MEDIA_GROUP_METHODS[method];
+        if (res.ok && extractor) {
+            await storeMessages(adapter, extractor(res.result));
+        }
+        return res;
+    };
+}
+/**
+ * Creates middleware that collects media group messages from incoming
+ * updates and hydrates the context with methods to retrieve stored
+ * media groups.
+ *
+ * @param adapter Storage adapter for persisting media group data (defaults to `MemorySessionStorage`)
+ * @param options Plugin options
+ * @returns A composer with middleware installed
+ *
+ * @example
+ * ```typescript
+ * import { Bot, Context, InputMediaBuilder } from "grammy";
+ * import {
+ *     type MediaGroupsFlavor,
+ *     mediaGroups,
+ * } from "@grammyjs/media-groups";
+ *
+ * type MyContext = Context & MediaGroupsFlavor;
+ *
+ * const bot = new Bot<MyContext>("<token>");
+ *
+ * // Uses MemorySessionStorage by default
+ * const mg = mediaGroups();
+ * bot.use(mg);
+ *
+ * // Install transformer for outgoing API responses
+ * bot.api.config.use(mg.transformer);
+ *
+ * // Programmatic access
+ * const messages = await mg.getMediaGroup("some-media-group-id");
+ *
+ * // In a command handler replying to a media group message
+ * bot.command("album", async (ctx) => {
+ *     const group = await ctx.mediaGroups.getForReply();
+ *     if (group) {
+ *         await ctx.replyWithMediaGroup(
+ *             group
+ *                 .map((msg) => {
+ *                     const opts = {
+ *                         caption: msg.caption,
+ *                         caption_entities: msg.caption_entities,
+ *                     };
+ *                     switch (true) {
+ *                         case "photo" in msg: {
+ *                             const id = msg.photo?.at(-1)?.file_id;
+ *                             return InputMediaBuilder.photo(id, opts);
+ *                         }
+ *                         case "video" in msg: {
+ *                             const id = msg.video?.file_id;
+ *                             return InputMediaBuilder.video(id, opts);
+ *                         }
+ *                         case "document" in msg: {
+ *                             const id = msg.document?.file_id;
+ *                             return InputMediaBuilder.document(id, opts);
+ *                         }
+ *                     }
+ *                 })
+ *                 .filter(Boolean),
+ *         );
+ *     }
+ * });
+ *
+ * // Access media group of current message via namespace
+ * bot.on("message", async (ctx) => {
+ *     const group = await ctx.mediaGroups.getForMsg();
+ *     if (group) console.log(`Album has ${group.length} items`);
+ * });
+ * ```
+ *
+ * @example Manual mode — disable automatic storing and use `ctx.mediaGroups.store()` instead:
+ * ```typescript
+ * const mg = mediaGroups(undefined, { autoStore: false });
+ * bot.use(mg);
+ *
+ * bot.on("message", async (ctx) => {
+ *     if (ctx.msg.media_group_id) {
+ *         await ctx.mediaGroups.store(ctx.msg);
+ *     }
+ * });
+ * ```
+ *
+ * @example Deleting a media group from storage:
+ * ```typescript
+ * // From within middleware
+ * await ctx.mediaGroups.delete("some-media-group-id");
+ *
+ * // From outside middleware
+ * await mg.deleteMediaGroup("some-media-group-id");
+ * ```
+ */
+export function mediaGroups(adapter = new MemorySessionStorage(), options = {}) {
+    const { autoStore = true } = options;
+    const composer = new Composer();
+    const getMediaGroup = async (mediaGroupId) => {
+        return await adapter.read(mediaGroupId);
+    };
+    const store = (message) => storeMessages(adapter, [message]);
+    const deleteMediaGroup = (mediaGroupId) => Promise.resolve(adapter.delete(mediaGroupId));
+    // Hydrate context and store incoming messages
+    composer.use(async (ctx, next) => {
+        // Resolve a media_group_id from a nested message
+        const getGroupFor = (nested) => {
+            const id = nested?.media_group_id;
+            return id ? getMediaGroup(id) : Promise.resolve(undefined);
+        };
+        ctx.mediaGroups = {
+            getForMsg: () => getGroupFor(ctx.msg),
+            getForReply: () => getGroupFor(ctx.msg?.reply_to_message),
+            getForPinned: () => getGroupFor(ctx.msg?.pinned_message),
+            store,
+            delete: deleteMediaGroup,
+        };
+        if (autoStore) {
+            const msg = ctx.msg;
+            const replyMsg = msg?.reply_to_message;
+            const pinnedMsg = msg?.pinned_message;
+            // Collect messages to store in batch
+            const toStore = [];
+            if (msg?.media_group_id)
+                toStore.push(msg);
+            if (replyMsg?.media_group_id)
+                toStore.push(replyMsg);
+            if (pinnedMsg?.media_group_id)
+                toStore.push(pinnedMsg);
+            if (toStore.length > 0) {
+                await storeMessages(adapter, toStore);
+            }
+        }
+        return next();
+    });
+    // Attach standalone helpers
+    const result = composer;
+    result.adapter = adapter;
+    result.transformer = mediaGroupTransformer(adapter);
+    result.getMediaGroup = getMediaGroup;
+    result.deleteMediaGroup = deleteMediaGroup;
+    return result;
+}
+export default mediaGroups;

package/out/storage.d.ts

@@ -0,0 +1,14 @@
+import type { Message, StorageAdapter } from "./deps.node.js";
+/**
+ * Static mapping of API methods to their result extraction logic.
+ * Keys are method names whose responses may contain messages with `media_group_id`.
+ * Values are functions that extract `Message[]` from the raw API result.
+ */
+export declare const MEDIA_GROUP_METHODS: Record<string, (result: any) => Message[]>;
+/**
+ * Stores messages in batch, grouped by `media_group_id`.
+ * Performs one read and one write per group instead of per message.
+ * Messages without `media_group_id` are skipped.
+ * Existing entries with the same `(message_id, chat.id)` are replaced in-place.
+ */
+export declare function storeMessages(adapter: StorageAdapter<Message[]>, messages: Message[]): Promise<void>;

package/out/storage.js

@@ -0,0 +1,38 @@
+/** Wraps a single Message in an array. */
+const toArray = (result) => [result];
+/** Returns a Message in an array if it's an object, or empty if `true` (inline edit). */
+// deno-lint-ignore no-explicit-any
+const toArrayIfObject = (result) => result !== null && typeof result === "object" ? [result] : [];
+/**
+ * Static mapping of API methods to their result extraction logic.
+ * Keys are method names whose responses may contain messages with `media_group_id`.
+ * Values are functions that extract `Message[]` from the raw API result.
+ */
+// deno-lint-ignore no-explicit-any
+export const MEDIA_GROUP_METHODS = {
+    sendMediaGroup: (result) => (Array.isArray(result) ? result : []),
+    forwardMessage: toArray,
+    editMessageMedia: toArrayIfObject,
+    editMessageCaption: toArrayIfObject,
+    editMessageReplyMarkup: toArrayIfObject,
+};
+/**
+ * Stores messages in batch, grouped by `media_group_id`.
+ * Performs one read and one write per group instead of per message.
+ * Messages without `media_group_id` are skipped.
+ * Existing entries with the same `(message_id, chat.id)` are replaced in-place.
+ */
+export async function storeMessages(adapter, messages) {
+    const groups = {};
+    for (const message of messages) {
+        const { media_group_id } = message;
+        if (!media_group_id)
+            continue;
+        const group = (groups[media_group_id] ??= (await adapter.read(media_group_id)) ??
+            []);
+        const index = group.findIndex((m) => m.message_id === message.message_id &&
+            m.chat.id === message.chat.id);
+        group[index >= 0 ? index : group.length] = message;
+    }
+    await Promise.all(Object.entries(groups).map(([key, value]) => adapter.write(key, value)));
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "grammy-media-groups",
+    "version": "0.0.0",
+    "description": "Media Groups Storage Plugin for grammY",
+    "homepage": "https://github.com/PonomareVlad/grammy-media-groups",
+    "main": "./out/mod.js",
+    "types": "./out/mod.d.ts",
+    "type": "module",
+    "scripts": {
+        "prepare": "npm run build",
+        "build": "deno2node tsconfig.json"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/PonomareVlad/grammy-media-groups.git"
+    },
+    "exports": {
+        ".": {
+            "types": "./out/mod.d.ts",
+            "default": "./out/mod.js"
+        }
+    },
+    "files": [
+        "out/"
+    ],
+    "author": "PonomareVlad",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/PonomareVlad/grammy-media-groups/issues"
+    },
+    "peerDependencies": {
+        "grammy": "^1.15.2"
+    },
+    "devDependencies": {
+        "deno2node": "^1.3.0"
+    },
+    "keywords": [
+        "grammY",
+        "Telegram bot framework",
+        "plugin",
+        "media group",
+        "album"
+    ]
+}