grammy-broadcast 2.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Smaznet
+
+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,603 @@
+# 📢 Grammy Broadcast Plugin
+
+<div align="center">
+
+**A powerful and professional plugin for broadcasting messages to all Telegram bot chats**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Grammy](https://img.shields.io/badge/Grammy-0088CC?style=for-the-badge&logo=telegram&logoColor=white)](https://grammy.dev/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)
+
+</div>
+
+---
+
+## ✨ Key Features
+
+### 🚀 Performance & Speed
+- ⚡ **Smart Rate Limiting**: Automatic Telegram rate limit management with auto-throttling on errors
+- 🔥 **Paid Broadcast Support**: Support for paid broadcasts at 1000 messages per second (requires Telegram Stars)
+- 📊 **Concurrent Sending**: Send messages concurrently with queue management
+- 🎯 **Queue Management**: Broadcast queue management with pause/resume/stop capabilities
+
+### 💾 Flexible Storage
+- 🔴 **Redis Storage**: For production environments and clusters
+- 💻 **Memory Storage**: For development and testing
+- 📁 **File Storage**: For local storage without Redis
+
+### 🎮 Full Control
+- ⏸️ **Pause/Resume**: Pause and resume sending at any time
+- 🛑 **Stop**: Complete stop and removal of broadcast
+- 📈 **Progress Tracking**: Track progress with percentage, sent count, and errors
+- 🔍 **Preview**: Preview messages before sending
+- 📌 **Pin Support**: Ability to pin messages after sending
+
+### 🎨 Send Types
+- 📋 **Copy Messages**: Copy messages while preserving content
+- ➡️ **Forward Messages**: Forward messages
+- ✍️ **Text Messages**: Send plain text
+- 📦 **Multi-Message**: Support for sending multiple messages in one broadcast
+
+### 🔐 Security & Access Control
+- 👥 **Sudo Users**: Define authorized users
+- 🔒 **Custom Permission**: Custom permission system
+- 🚫 **Auto Block Management**: Automatic management of blocked users
+
+### 🌐 Cluster Support
+- 🔄 **Multi-Instance**: Support for multiple instances
+- 🎯 **Main Instance**: Designate main instance for queue processing
+
+---
+
+## 📦 Installation
+
+```bash
+npm install grammy-broadcast
+# or
+yarn add grammy-broadcast
+# or
+pnpm add grammy-broadcast
+```
+
+### Requirements
+
+```bash
+npm install grammy ioredis
+# or
+yarn add grammy ioredis
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic Example with Redis
+
+```typescript
+import { Bot } from "grammy";
+import { createBroadcaster, RedisStorage } from "grammy-broadcast";
+import Redis from "ioredis";
+
+const bot = new Bot("YOUR_BOT_TOKEN");
+const redis = new Redis();
+
+const broadcaster = createBroadcaster({
+    storage: new RedisStorage(redis),
+    isMainInstance: true, // For clusters, set true only on the main instance
+    sudoUsers: [123456789], // Authorized user IDs
+    getApi: async (botId) => bot.api, // or bot.api for single bot
+    getBroadcastChats: async (botId, offset, limit, filter) => {
+        // You can use any database here
+        // Example with MongoDB:
+        const users = await UserModel.find({ blocked: { $ne: true } })
+            .skip(offset)
+            .limit(limit)
+            .select("uid")
+            .lean();
+        return users.map(u => u.uid);
+    },
+    setRestricted: async (botId, chatId, type) => {
+        // Manage blocked users
+        if (type === 'block' || type === 'deactivated') {
+            await UserModel.updateOne({ uid: chatId }, { blocked: true });
+        }
+    }
+});
+
+// Add middleware to bot
+bot.use(broadcaster.getMiddleware());
+
+bot.start();
+```
+
+### Example with Memory Storage (for testing)
+
+```typescript
+import { Bot } from "grammy";
+import { createBroadcaster, MemoryStorage } from "grammy-broadcast";
+
+const bot = new Bot("YOUR_BOT_TOKEN");
+
+const broadcaster = createBroadcaster({
+    storage: new MemoryStorage(),
+    isMainInstance: true,
+    sudoUsers: [123456789],
+    getApi: async () => bot.api,
+    getBroadcastChats: async (botId, offset, limit, filter) => {
+        // Test chat list
+        return [123456, 789012, 345678];
+    }
+});
+
+bot.use(broadcaster.getMiddleware());
+bot.start();
+```
+
+### Example with File Storage
+
+```typescript
+import { Bot } from "grammy";
+import { createBroadcaster, FileStorage } from "grammy-broadcast";
+
+const bot = new Bot("YOUR_BOT_TOKEN");
+
+const broadcaster = createBroadcaster({
+    storage: new FileStorage("./broadcast-data"), // Storage path
+    isMainInstance: true,
+    sudoUsers: [123456789],
+    getApi: async () => bot.api,
+    getBroadcastChats: async (botId, offset, limit, filter) => {
+        // Chat retrieval logic
+        return [];
+    }
+});
+
+bot.use(broadcaster.getMiddleware());
+bot.start();
+```
+
+---
+
+## 📖 Usage Guide
+
+### Available Commands
+
+#### 1️⃣ `/broadcast <type> [filter]`
+Send broadcast with specified type
+
+**Parameters:**
+- `type`: Send type (`copy` or `forward`)
+- `filter`: Optional filter for selecting chats (passed to `getBroadcastChats`)
+
+**Examples:**
+```
+/broadcast copy users
+/broadcast forward groups
+```
+
+#### 2️⃣ `/copy [filter]`
+Shortcut for `/broadcast copy`
+
+**Examples:**
+```
+/copy users
+/copy
+```
+
+#### 3️⃣ `/forward [filter]`
+Shortcut for `/broadcast forward`
+
+**Examples:**
+```
+/forward groups
+/forward
+```
+
+#### 4️⃣ `/addmsg <broadcast_id>`
+Add message to existing broadcast
+
+**Example:**
+```
+/addmsg abc123
+```
+
+### Usage Steps
+
+1. **Create Broadcast:**
+   - Reply to the message you want to broadcast
+   - Send `/copy` or `/forward` command
+   - You'll receive a broadcast ID
+
+2. **Add More Messages (Optional):**
+   - Reply to another message
+   - Send `/addmsg <broadcast_id>` command
+
+3. **Settings (Optional):**
+   - **Preview** button for preview
+   - **Pin** button to pin messages after sending
+
+4. **Start Sending:**
+   - Click **Start** button
+   - Sending progress is displayed in real-time
+
+5. **Control Sending:**
+   - **Pause**: Temporary pause
+   - **Resume**: Resume sending
+   - **Stop**: Complete stop
+
+---
+
+## ⚙️ Advanced Configuration
+
+### BroadcastOptions
+
+```typescript
+interface BroadcastOptions {
+    // Storage instance (required)
+    storage: Storage;
+    
+    // Function to get chats (required)
+    getBroadcastChats: (botId: number, offset: number, limit: number, filter?: string) => Promise<string[] | number[]>;
+    
+    // API instance (required)
+    getApi: (botId: number) => Promise<Api> | Api;
+    
+    // Designate main instance (required)
+    isMainInstance: boolean;
+    
+    // List of authorized users
+    sudoUsers?: number[];
+    
+    // Custom permission check function
+    hasPermission?: (ctx: Context) => boolean | Promise<boolean>;
+    
+    // Manage blocked users
+    setRestricted?: (botId: number, chatId: string, type: 'block' | 'deactivated' | 'banned' | 'restricted') => Promise<void>;
+    
+    // Number of chats processed per chunk (default: 100)
+    chunkSize?: number;
+    
+    // Redis key prefix (default: 'brdc:')
+    keyPrefix?: string;
+    
+    // Progress report frequency in milliseconds (default: 60000)
+    reportFrequency?: number;
+    
+    // Queue check interval in milliseconds (default: 60000)
+    checkQueueInterval?: number;
+    
+    // Progress callback function (optional)
+    progressCallback?: (id: string, sent: number, error: number, total: number) => void;
+    
+    // Enable Paid Broadcast (default: false)
+    allowPaidBroadcast?: boolean;
+    
+    // Customize command names
+    cmds?: {
+        broadcast?: string;  // default: 'broadcast'
+        copy?: string;        // default: 'copy'
+        forward?: string;     // default: 'forward'
+        addmsg?: string;      // default: 'addmsg'
+    };
+}
+```
+
+### Complete Example with All Settings
+
+```typescript
+import { Bot, Context } from "grammy";
+import { createBroadcaster, RedisStorage } from "grammy-broadcast";
+import Redis from "ioredis";
+
+const bot = new Bot("YOUR_BOT_TOKEN");
+const redis = new Redis();
+
+const broadcaster = createBroadcaster({
+    // Storage
+    storage: new RedisStorage(redis),
+    
+    // Get chats with filter
+    getBroadcastChats: async (botId, offset, limit, filter) => {
+        if (filter === 'users') {
+            const users = await UserModel.find({ blocked: { $ne: true } })
+                .skip(offset)
+                .limit(limit)
+                .select("uid")
+                .lean();
+            return users.map(u => u.uid);
+        }
+        
+        if (filter === 'groups') {
+            const groups = await GroupModel.find({ botRemoved: { $ne: true } })
+                .skip(offset)
+                .limit(limit)
+                .select("chatId")
+                .lean();
+            return groups.map(g => g.chatId);
+        }
+        
+        if (filter === 'premium') {
+            const premiumUsers = await UserModel.find({ 
+                premium: true, 
+                blocked: { $ne: true } 
+            })
+                .skip(offset)
+                .limit(limit)
+                .select("uid")
+                .lean();
+            return premiumUsers.map(u => u.uid);
+        }
+        
+        // No filter - all chats
+        const allChats = await ChatModel.find({})
+            .skip(offset)
+            .limit(limit)
+            .select("chatId")
+            .lean();
+        return allChats.map(c => c.chatId);
+    },
+    
+    // Manage blocked users
+    setRestricted: async (botId, chatId, type) => {
+        if (type === 'block' || type === 'deactivated') {
+            await UserModel.updateOne(
+                { uid: chatId }, 
+                { blocked: true, blockedAt: new Date() }
+            );
+        } else if (type === 'banned' || type === 'restricted') {
+            await GroupModel.updateOne(
+                { chatId }, 
+                { botRemoved: true, removedAt: new Date() }
+            );
+        }
+    },
+    
+    // API instance
+    getApi: async (botId) => bot.api,
+    
+    // Settings
+    isMainInstance: true,
+    sudoUsers: [123456789, 987654321],
+    
+    // Or use custom function for permissions
+    // hasPermission: async (ctx: Context) => {
+    //     const user = await UserModel.findOne({ uid: ctx.from?.id });
+    //     return user?.isAdmin === true;
+    // },
+    
+    // Advanced settings
+    chunkSize: 50,                    // Process 50 chats per batch
+    keyPrefix: 'mybot:brdc:',         // Custom prefix
+    reportFrequency: 30000,            // Report every 30 seconds
+    checkQueueInterval: 10000,        // Check queue every 10 seconds
+    allowPaidBroadcast: true,         // Enable paid broadcast
+    
+    // Progress callback
+    progressCallback: (id, sent, error, total) => {
+        console.log(`Broadcast ${id}: ${sent}/${total} sent, ${error} errors`);
+    },
+    
+    // Customize commands
+    cmds: {
+        broadcast: 'bbroadcast',
+        copy: 'bcopy',
+        forward: 'bforward',
+        addmsg: 'baddmsg'
+    }
+});
+
+bot.use(broadcaster.getMiddleware());
+bot.start();
+```
+
+---
+
+## 🎯 Practical Examples
+
+### Example 1: Broadcast to Specific Users
+
+```typescript
+// Send to premium users
+/broadcast copy premium
+
+// Send to active groups
+/broadcast forward active_groups
+```
+
+### Example 2: Using in Cluster
+
+```typescript
+// Main instance
+const broadcaster = createBroadcaster({
+    // ...
+    isMainInstance: true,  // Only in this instance
+});
+
+// Other instances
+const broadcaster = createBroadcaster({
+    // ...
+    isMainInstance: false,  // In other instances
+});
+```
+
+### Example 3: Error Management
+
+```typescript
+const broadcaster = createBroadcaster({
+    // ...
+    setRestricted: async (botId, chatId, type) => {
+        console.log(`Chat ${chatId} restricted: ${type}`);
+        
+        // Save to log
+        await LogModel.create({
+            chatId,
+            type,
+            timestamp: new Date()
+        });
+        
+        // Update database
+        if (type === 'block') {
+            await UserModel.updateOne(
+                { uid: chatId },
+                { blocked: true, blockedReason: 'user_blocked_bot' }
+            );
+        }
+    }
+});
+```
+
+### Example 4: Using Progress Callback
+
+```typescript
+const broadcaster = createBroadcaster({
+    // ...
+    progressCallback: async (id, sent, error, total) => {
+        // Send report to admin
+        const progress = ((sent + error) / total * 100).toFixed(2);
+        await bot.api.sendMessage(
+            ADMIN_CHAT_ID,
+            `📊 Broadcast ${id}\n` +
+            `✅ Sent: ${sent}\n` +
+            `❌ Errors: ${error}\n` +
+            `📈 Progress: ${progress}%`
+        );
+    }
+});
+```
+
+---
+
+## 🔧 Storage Implementations
+
+### RedisStorage
+
+For use in production and cluster environments:
+
+```typescript
+import { RedisStorage } from "grammy-broadcast";
+import Redis from "ioredis";
+
+const redis = new Redis({
+    host: 'localhost',
+    port: 6379,
+    // or connection string
+    // host: 'redis://localhost:6379'
+});
+
+const storage = new RedisStorage(redis);
+```
+
+### MemoryStorage
+
+For development and testing (data stored in memory):
+
+```typescript
+import { MemoryStorage } from "grammy-broadcast";
+
+const storage = new MemoryStorage();
+```
+
+### FileStorage
+
+For local storage without Redis:
+
+```typescript
+import { FileStorage } from "grammy-broadcast";
+
+const storage = new FileStorage("./broadcast-storage");
+```
+
+---
+
+## 📊 Progress Display
+
+The plugin automatically displays broadcast progress:
+
+```
+⌛ Broadcasting
+████████░░ (80%)
+⌛ Progress: 800/1000
+✅ Sent: 750
+❌ Error: 50 (5%)
+⚡ Rate: 30 msg/sec
+```
+
+Control buttons:
+- **Progress Bar**: Show progress details
+- **Pause**: Temporary pause
+- **Stop**: Complete stop
+
+---
+
+## 🛡️ Error Management
+
+The plugin automatically handles the following errors:
+
+- ✅ **Blocked Users**: Blocked users
+- ✅ **Deactivated Accounts**: Deactivated accounts
+- ✅ **Kicked from Groups**: Kicked from groups
+- ✅ **Restricted**: Access restrictions
+- ✅ **Rate Limiting**: Automatic Telegram rate limit management
+
+Errors are automatically handled in the `setRestricted` callback.
+
+---
+
+## 🚀 Paid Broadcast
+
+To use Paid Broadcast feature (sending at 1000 messages/second):
+
+```typescript
+const broadcaster = createBroadcaster({
+    // ...
+    allowPaidBroadcast: true,  // Requires Telegram Stars
+});
+```
+
+**Note:** This feature requires Telegram Stars and is paid.
+
+---
+
+## 📝 Important Notes
+
+1. **Main Instance**: In cluster environments, only one instance should have `isMainInstance: true`
+2. **Storage**: Always use Redis for production
+3. **Rate Limiting**: The plugin automatically manages rate limiting
+4. **Error Handling**: Always implement `setRestricted`
+5. **Database**: You can use any database for `getBroadcastChats`
+
+---
+
+## 🤝 Contributing
+
+Contributions are always welcome! Please make sure before submitting a PR that:
+
+- ✅ Your code follows the project standards
+- ✅ You've added necessary tests
+- ✅ You've updated the documentation
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT](LICENSE) License.
+
+---
+
+## 👤 Author
+
+**Aria** - [smaznet98@gmail.com](mailto:smaznet98@gmail.com)
+
+---
+
+## ⭐ Stars
+
+If this project was useful to you, please give it a star ⭐!
+
+---
+
+<div align="center">
+
+**Made with ❤️ for the Grammy community**
+
+</div>