Add chat member filters

README.md

@@ -1,10 +1,132 @@
 # Chat members plugin for grammY
 
-This plugin watches for `chat_member` updates and stores a list of users, their statuses and permissions for each chat
-in which they and the bot are a member.
+This plugin makes it easy to work with `ChatMember` objects, by offering a convenient way to listen for changes in the
+form of custom filters, and by storing and updating the objects.
 
 ## Usage
 
+### Chat member filters
+
+You can listen for two kinds of updates regarding chat members using a telegram bot: `chat_member` and `my_chat_member`,
+both of them specify the old and new status of the user.
+
+- `my_chat_member` updates are received by your bot by default and they inform you about the status of the bot being
+  updated in any chat, as well as users blocking the bot;
+- `chat_member` updates are only received if you specifically include them in the list of allowed updates, they notify
+  about any status changes for users in chats **where your bot is admin**.
+
+Filters specify the status before and after the change, allowing you to react to every type of transition you're
+interested in. Within the handler, types of `old_chat_member` and `new_chat_member` are updated accordingly.
+
+```typescript
+const bot = new Bot(process.env.BOT_TOKEN!);
+const groups = bot.chatType(["group", "supergroup"]);
+
+groups.filter(myChatMemberFilter("out", "regular"), async (ctx) => {
+    await ctx.reply("Hello, thank you for adding me to the group!");
+});
+
+groups.filter(myChatMemberFilter("out", "admin"), async (ctx) => {
+    await ctx.reply("Hello, thank you for adding me to the group as admin!");
+});
+
+groups.filter(myChatMemberFilter("regular", "admin"), async (ctx) => {
+    await ctx.reply("I was promoted to admin!");
+});
+
+groups.filter(myChatMemberFilter("admin", "regular"), async (ctx) => {
+    await ctx.reply("I am no longer admin");
+});
+
+groups.filter(chatMemberFilter("out", "in"), async (ctx) => {
+    const user = ctx.chatMember.new_chat_member.user;
+    await ctx.reply(
+        `Welcome <b>${escapeHtml(user.first_name)}</> to the group!`,
+        { parse_mode: "HTML" },
+    );
+});
+
+bot.start({
+    allowed_updates: [...DEFAULT_UPDATE_TYPES, "chat_member"],
+    onStart: (me) => console.log("Listening to updates as", me.username),
+});
+```
+
+Filters include the regular Telegram statuses (owner, administrator, member, restricted, left, kicked) and some
+additional ones for convenience:
+
+- restricted_in: a member of the chat with restrictions;
+- restricted_out: not a member of the chat, has restrictions;
+- in: a member of the chat (administrator, creator, member, restricted_in);
+- out: not a member of the chat (left, kicked, restricted_out);
+- free: a member of the chat that isn't restricted (administrator, creator, member);
+- admin: an admin of the chat (administrator, creator);
+- regular: a non-admin member of the chat (member, restricted_in).
+
+You can create your custom groupings of chat member types by passing an array instead of a string:
+
+```typescript
+groups.filter(
+    chatMemberFilter(["restricted", "kicked"], ["free", "left"]),
+    async (ctx) => {
+        const from = ctx.from;
+        const { status: oldStatus, user } = ctx.chatMember.old_chat_member;
+        await ctx.reply(
+            `<b>${escapeHtml(from.first_name)}</> lifted ` +
+                `${oldStatus === "kicked" ? "ban" : "restrictions"} ` +
+                `from <b>${escapeHtml(user.first_name)}</>`,
+            { parse_mode: "HTML" },
+        );
+    },
+);
+```
+
+#### Example usage
+
+The best way to use the filters is to pick a set of relevant statuses, for example 'out', 'regular' and 'admin', then
+make a table of the transitions between them:
+
+| ↱           | Out         | Regular              | Admin               |
+| ----------- | ----------- | -------------------- | ------------------- |
+| **Out**     | ban-changed | join                 | join-and-promoted   |
+| **Regular** | exit        | restrictions-changed | promoted            |
+| **Admin**   | exit        | demoted              | permissions-changed |
+
+Assign a listener to all the transitions that are relevant to your use-case.
+
+Combine these filters with `bot.chatType` to only listen for transitions for a specific type of chat. Add a middleware
+to listen to all updates as a way to perform common operations (like updating your database) before handing off control
+to a specific handler.
+
+```typescript
+const groups = bot.chatType(["group", "supergroup"]);
+
+groups.on("chat_member", (ctx, next) => {
+    // ran on all updates of type chat_member
+    const {
+        old_chat_member: { status: oldStatus },
+        new_chat_member: { user, status },
+        from,
+        chat,
+    } = ctx.chatMember;
+    console.log(
+        `In group ${chat.id} user ${from.id} changed status of ${user.id}:`,
+        `${oldStatus} -> ${status}`,
+    );
+
+    // update database data here
+
+    return next();
+});
+
+// specific handlers
+
+groups.filter(chatMemberFilter("out", "in"), async (ctx, next) => {
+    const { new_chat_member: { user } } = ctx.chatMember;
+    await ctx.reply(`Welcome ${user.first_name}!`);
+});
+```
+
 ### Storing chat members
 
 You can use a valid grammY [storage adapter](https://grammy.dev/plugins/session.html#known-storage-adapters) or an
@@ -25,8 +147,8 @@ const bot = new Bot<MyContext>("<your bot token>");
 bot.use(chatMembers(adapter));
 
 bot.start({
-  allowed_updates: ["chat_member", "message"],
-  onStart: ({ username }) => console.log(`Listening as ${username}`),
+    allowed_updates: ["chat_member", "message"],
+    onStart: ({ username }) => console.log(`Listening as ${username}`),
 });
 ```
 
@@ -41,9 +163,9 @@ Here's an example:
 
 ```typescript
 bot.on("message", async (ctx) => {
-  const chatMember = await ctx.chatMembers.getChatMember();
+    const chatMember = await ctx.chatMembers.getChatMember();
 
-  return ctx.reply(`Hello, ${chatMember.user.first_name}! I see you are a ${chatMember.status} of this chat!`);
+    return ctx.reply(`Hello, ${chatMember.user.first_name}! I see you are a ${chatMember.status} of this chat!`);
 });
 ```
 

src/README.md

@@ -1,10 +1,132 @@
 # Chat members plugin for grammY
 
-This plugin watches for `chat_member` updates and stores a list of users, their statuses and permissions for each chat
-in which they and the bot are a member.
+This plugin makes it easy to work with `ChatMember` objects, by offering a convenient way to listen for changes in the
+form of custom filters, and by storing and updating the objects.
 
 ## Usage
 
+### Chat member filters
+
+You can listen for two kinds of updates regarding chat members using a telegram bot: `chat_member` and `my_chat_member`,
+both of them specify the old and new status of the user.
+
+- `my_chat_member` updates are received by your bot by default and they inform you about the status of the bot being
+  updated in any chat, as well as users blocking the bot;
+- `chat_member` updates are only received if you specifically include them in the list of allowed updates, they notify
+  about any status changes for users in chats **where your bot is admin**.
+
+Filters specify the status before and after the change, allowing you to react to every type of transition you're
+interested in. Within the handler, types of `old_chat_member` and `new_chat_member` are updated accordingly.
+
+```typescript
+const bot = new Bot(process.env.BOT_TOKEN!);
+const groups = bot.chatType(["group", "supergroup"]);
+
+groups.filter(myChatMemberFilter("out", "regular"), async (ctx) => {
+    await ctx.reply("Hello, thank you for adding me to the group!");
+});
+
+groups.filter(myChatMemberFilter("out", "admin"), async (ctx) => {
+    await ctx.reply("Hello, thank you for adding me to the group as admin!");
+});
+
+groups.filter(myChatMemberFilter("regular", "admin"), async (ctx) => {
+    await ctx.reply("I was promoted to admin!");
+});
+
+groups.filter(myChatMemberFilter("admin", "regular"), async (ctx) => {
+    await ctx.reply("I am no longer admin");
+});
+
+groups.filter(chatMemberFilter("out", "in"), async (ctx) => {
+    const user = ctx.chatMember.new_chat_member.user;
+    await ctx.reply(
+        `Welcome <b>${escapeHtml(user.first_name)}</> to the group!`,
+        { parse_mode: "HTML" },
+    );
+});
+
+bot.start({
+    allowed_updates: [...DEFAULT_UPDATE_TYPES, "chat_member"],
+    onStart: (me) => console.log("Listening to updates as", me.username),
+});
+```
+
+Filters include the regular Telegram statuses (owner, administrator, member, restricted, left, kicked) and some
+additional ones for convenience:
+
+- restricted_in: a member of the chat with restrictions;
+- restricted_out: not a member of the chat, has restrictions;
+- in: a member of the chat (administrator, creator, member, restricted_in);
+- out: not a member of the chat (left, kicked, restricted_out);
+- free: a member of the chat that isn't restricted (administrator, creator, member);
+- admin: an admin of the chat (administrator, creator);
+- regular: a non-admin member of the chat (member, restricted_in).
+
+You can create your custom groupings of chat member types by passing an array instead of a string:
+
+```typescript
+groups.filter(
+    chatMemberFilter(["restricted", "kicked"], ["free", "left"]),
+    async (ctx) => {
+        const from = ctx.from;
+        const { status: oldStatus, user } = ctx.chatMember.old_chat_member;
+        await ctx.reply(
+            `<b>${escapeHtml(from.first_name)}</> lifted ` +
+                `${oldStatus === "kicked" ? "ban" : "restrictions"} ` +
+                `from <b>${escapeHtml(user.first_name)}</>`,
+            { parse_mode: "HTML" },
+        );
+    },
+);
+```
+
+#### Example usage
+
+The best way to use the filters is to pick a set of relevant statuses, for example 'out', 'regular' and 'admin', then
+make a table of the transitions between them:
+
+| ↱           | Out         | Regular              | Admin               |
+| ----------- | ----------- | -------------------- | ------------------- |
+| **Out**     | ban-changed | join                 | join-and-promoted   |
+| **Regular** | exit        | restrictions-changed | promoted            |
+| **Admin**   | exit        | demoted              | permissions-changed |
+
+Assign a listener to all the transitions that are relevant to your use-case.
+
+Combine these filters with `bot.chatType` to only listen for transitions for a specific type of chat. Add a middleware
+to listen to all updates as a way to perform common operations (like updating your database) before handing off control
+to a specific handler.
+
+```typescript
+const groups = bot.chatType(["group", "supergroup"]);
+
+groups.on("chat_member", (ctx, next) => {
+    // ran on all updates of type chat_member
+    const {
+        old_chat_member: { status: oldStatus },
+        new_chat_member: { user, status },
+        from,
+        chat,
+    } = ctx.chatMember;
+    console.log(
+        `In group ${chat.id} user ${from.id} changed status of ${user.id}:`,
+        `${oldStatus} -> ${status}`,
+    );
+
+    // update database data here
+
+    return next();
+});
+
+// specific handlers
+
+groups.filter(chatMemberFilter("out", "in"), async (ctx, next) => {
+    const { new_chat_member: { user } } = ctx.chatMember;
+    await ctx.reply(`Welcome ${user.first_name}!`);
+});
+```
+
 ### Storing chat members
 
 You can use a valid grammY [storage adapter](https://grammy.dev/plugins/session.html#known-storage-adapters) or an
@@ -25,8 +147,8 @@ const bot = new Bot<MyContext>("<your bot token>");
 bot.use(chatMembers(adapter));
 
 bot.start({
-  allowed_updates: ["chat_member", "message"],
-  onStart: ({ username }) => console.log(`Listening as ${username}`),
+    allowed_updates: ["chat_member", "message"],
+    onStart: ({ username }) => console.log(`Listening as ${username}`),
 });
 ```
 
@@ -41,9 +163,9 @@ Here's an example:
 
 ```typescript
 bot.on("message", async (ctx) => {
-  const chatMember = await ctx.chatMembers.getChatMember();
+    const chatMember = await ctx.chatMembers.getChatMember();
 
-  return ctx.reply(`Hello, ${chatMember.user.first_name}! I see you are a ${chatMember.status} of this chat!`);
+    return ctx.reply(`Hello, ${chatMember.user.first_name}! I see you are a ${chatMember.status} of this chat!`);
 });
 ```
 

src/deps.deno.ts

@@ -1,2 +1,14 @@
-export { Composer, Context, type StorageAdapter } from "https://lib.deno.dev/x/grammy@v1/mod.ts";
-export type { Chat, ChatMember, ChatMemberUpdated, User } from "https://lib.deno.dev/x/grammy@v1/types.ts";
+export { Api, Composer, Context, type Filter, type StorageAdapter } from "https://lib.deno.dev/x/grammy@v1/mod.ts";
+export type {
+    Chat,
+    ChatMember,
+    ChatMemberAdministrator,
+    ChatMemberBanned,
+    ChatMemberLeft,
+    ChatMemberMember,
+    ChatMemberOwner,
+    ChatMemberRestricted,
+    ChatMemberUpdated,
+    User,
+    UserFromGetMe,
+} from "https://lib.deno.dev/x/grammy@v1/types.ts";

src/deps.node.ts

@@ -1,2 +1,14 @@
-export { Composer, Context, type StorageAdapter } from "grammy";
-export type { Chat, ChatMember, ChatMemberUpdated, User } from "grammy/types";
+export { Api, Composer, Context, type Filter, type StorageAdapter } from "grammy";
+export type {
+    Chat,
+    ChatMember,
+    ChatMemberAdministrator,
+    ChatMemberBanned,
+    ChatMemberLeft,
+    ChatMemberMember,
+    ChatMemberOwner,
+    ChatMemberRestricted,
+    ChatMemberUpdated,
+    User,
+    UserFromGetMe,
+} from "grammy/types";