@entergreat/messenger 1.0.0

package/.npmrc.example

@@ -0,0 +1,12 @@
+# NPM Registry Configuration
+# Copy this file to .npmrc and configure for your setup
+
+# For GitHub Packages (private package)
+# @entergreat:registry=https://npm.pkg.github.com
+# //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+
+# For private npm registry
+# registry=https://your-private-registry.com
+
+# Standard npm registry (public packages)
+registry=https://registry.npmjs.org/

package/README.md

@@ -0,0 +1,211 @@
+# @entergreat/messenger
+
+Telegram messaging library for notifications and interactive bots.
+
+## Install
+
+```bash
+npm install @entergreat/messenger
+```
+
+## Quick Start
+
+### Send Notifications (eg-light)
+
+```javascript
+import { Messenger, telegram } from '@entergreat/messenger';
+
+const messenger = new Messenger();
+messenger.addPlatform('telegram', telegram({
+  token: process.env.TELEGRAM_BOT_TOKEN,
+  chatId: process.env.TELEGRAM_CHAT_ID
+}));
+
+// Send text
+await messenger.sendText(null, 'Pipeline complete!');
+
+// Send file
+await messenger.sendFile(null, '/path/to/results.csv', {
+  caption: 'Results',
+  fileName: 'results.csv'
+});
+```
+
+### Interactive Bot (eg-bot)
+
+```javascript
+import { Messenger, telegram } from '@entergreat/messenger';
+
+const messenger = new Messenger();
+
+messenger
+  .addPlatform('telegram', telegram({
+    token: process.env.TELEGRAM_BOT_TOKEN,
+    allowDynamicRecipients: true,
+    allowedChatIds: '123,456,789'
+  }))
+  .command('/start', async (ctx) => {
+    await ctx.reply('Welcome!');
+  })
+  .command('/echo', async (ctx) => {
+    const text = ctx.args.join(' ');
+    await ctx.reply(`You said: ${text}`);
+  });
+
+await messenger.startReceiving();
+```
+
+### Conversation Flow
+
+```javascript
+import { ConversationManager } from '@entergreat/messenger';
+
+messenger.command('/register', async (ctx) => {
+  const conv = new ConversationManager([
+    {
+      field: 'name',
+      prompt: 'What is your name?',
+      required: true
+    },
+    {
+      field: 'email',
+      prompt: 'What is your email?',
+      required: true,
+      validate: (v) => v.includes('@') ? null : 'Invalid email'
+    }
+  ], {
+    onComplete: async (data, reply) => {
+      await reply(`Done! Name: ${data.name}, Email: ${data.email}`);
+    }
+  });
+
+  ctx.messenger.setConversation(ctx.chatId, conv);
+  await ctx.reply(conv.start());
+});
+```
+
+### Rate Limiting
+
+```javascript
+import { RateLimiter } from '@entergreat/messenger';
+
+const limiter = new RateLimiter({ maxRequests: 3, windowMs: 24 * 60 * 60 * 1000 });
+
+messenger.command('/limited', async (ctx) => {
+  const check = limiter.check(ctx.userId);
+  if (!check.allowed) {
+    await ctx.reply(`Rate limit exceeded. Try again in ${check.resetIn}`);
+    return;
+  }
+  limiter.increment(ctx.userId);
+  await ctx.reply(`OK! ${check.remaining - 1} uses left today`);
+});
+```
+
+## Config
+
+### Fixed Recipient (Notifications)
+
+```javascript
+telegram({
+  token: 'bot_token',
+  chatId: '123456789',
+  parseMode: 'Markdown'  // or 'HTML'
+})
+```
+
+### Dynamic Recipients (Bots)
+
+```javascript
+telegram({
+  token: 'bot_token',
+  allowDynamicRecipients: true,
+  allowedChatIds: [123, 456, 789],  // whitelist
+  pollTimeout: 30  // polling timeout in seconds
+})
+```
+
+## API
+
+### Messenger
+
+- `addPlatform(name, adapter)` - Add Telegram adapter
+- `sendText(recipient, text, options)` - Send text message
+- `sendFile(recipient, path, options)` - Send file
+- `sendImage(recipient, path, options)` - Send image
+- `command(name, handler)` - Register command
+- `onMessage(handler)` - Register message handler
+- `startReceiving()` - Start polling
+- `stopReceiving()` - Stop polling
+- `healthCheck()` - Check bot status
+
+### Context Object
+
+```javascript
+{
+  chatId: 123456789,
+  userId: 987654321,
+  message: 'Hello',
+  reply: async (text) => {},
+  messenger: messengerInstance
+}
+```
+
+### ConversationManager
+
+```javascript
+new ConversationManager(steps, { onComplete, onCancel })
+
+// Step format:
+{
+  field: 'name',
+  prompt: 'Question?',
+  required: true,
+  default: 'value',
+  validate: (value) => error || null,
+  transform: (value) => transformedValue
+}
+```
+
+### RateLimiter
+
+```javascript
+new RateLimiter({ maxRequests: 3, windowMs: 86400000 })
+
+limiter.check(userId)      // { allowed, remaining, resetIn }
+limiter.increment(userId)  // Record usage
+```
+
+## Migration
+
+### From eg-light
+
+```javascript
+// Before
+const delivery = new DeliveryService();
+await delivery.sendUpdate('Message');
+
+// After
+const messenger = new Messenger();
+messenger.addPlatform('telegram', telegram({ token, chatId }));
+await messenger.sendText(null, 'Message');
+```
+
+### From eg-bot
+
+```javascript
+// Before
+const bot = new Bot(token);
+bot.register('/start', handler);
+await bot.start();
+
+// After
+const messenger = new Messenger();
+messenger.addPlatform('telegram', telegram({ token, allowDynamicRecipients: true }));
+messenger.command('/start', handler);
+await messenger.startReceiving();
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@entergreat/messenger",
+  "version": "1.0.0",
+  "description": "Multi-platform messaging and bot framework for EnterGreat services",
+  "main": "src/index.js",
+  "type": "module",
+  "keywords": [
+    "messenger",
+    "telegram",
+    "slack",
+    "email",
+    "whatsapp",
+    "teams",
+    "bot",
+    "notifications"
+  ],
+  "author": "EnterGreat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/entergreat/messenger.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "logger-standard": "^1.0.2"
+  }
+}

package/src/core/Messenger.js

@@ -0,0 +1,96 @@
+export class Messenger {
+  constructor() {
+    this.platform = null;
+    this.adapter = null;
+    this.receiver = null;
+    this.commandHandlers = new Map();
+    this.messageHandlers = [];
+    this.conversations = new Map();
+  }
+
+  addPlatform(name, adapter) {
+    this.platform = name;
+    this.adapter = adapter;
+
+    const ReceiverClass = adapter.getReceiverClass();
+    if (ReceiverClass) {
+      this.receiver = new ReceiverClass(adapter, this);
+    }
+
+    return this;
+  }
+
+  async send(recipient, content, options = {}) {
+    const method = options.method || 'sendText';
+    return await this.adapter[method](recipient, content, options);
+  }
+
+  async sendText(recipient, text, options = {}) {
+    return await this.adapter.sendText(recipient, text, options);
+  }
+
+  async sendFile(recipient, filePath, options = {}) {
+    return await this.adapter.sendFile(recipient, filePath, options);
+  }
+
+  async sendImage(recipient, imagePath, options = {}) {
+    return await this.adapter.sendImage(recipient, imagePath, options);
+  }
+
+  command(commandName, handler) {
+    this.commandHandlers.set(commandName, handler);
+    return this;
+  }
+
+  onMessage(handler) {
+    this.messageHandlers.push(handler);
+    return this;
+  }
+
+  conversation(chatId) {
+    return this.conversations.get(chatId);
+  }
+
+  setConversation(chatId, conversation) {
+    this.conversations.set(chatId, conversation);
+  }
+
+  clearConversation(chatId) {
+    this.conversations.delete(chatId);
+  }
+
+  async handleCommand(command, context) {
+    const handler = this.commandHandlers.get(command);
+    if (handler) {
+      await handler(context);
+      return true;
+    }
+    return false;
+  }
+
+  async handleMessage(context) {
+    for (const handler of this.messageHandlers) {
+      if (await handler(context)) return true;
+    }
+    return false;
+  }
+
+  async startReceiving() {
+    if (!this.receiver) {
+      throw new Error('Platform does not support receiving messages');
+    }
+    await this.receiver.start();
+    return this;
+  }
+
+  async stopReceiving() {
+    if (this.receiver) {
+      await this.receiver.stop();
+    }
+    return this;
+  }
+
+  async healthCheck() {
+    return await this.adapter.healthCheck();
+  }
+}

package/src/core/PlatformAdapter.js

@@ -0,0 +1,30 @@
+export class PlatformAdapter {
+  constructor(config) {
+    this.config = config;
+    this.validateConfig();
+  }
+
+  validateConfig() {
+    throw new Error('validateConfig() must be implemented');
+  }
+
+  async sendText(recipient, text, options) {
+    throw new Error('sendText() must be implemented');
+  }
+
+  async sendFile(recipient, filePath, options) {
+    throw new Error('sendFile() must be implemented');
+  }
+
+  async sendImage(recipient, imagePath, options) {
+    throw new Error('sendImage() must be implemented');
+  }
+
+  getReceiverClass() {
+    return null;
+  }
+
+  async healthCheck() {
+    return { status: 'ok' };
+  }
+}

package/src/features/conversation/ConversationManager.js

@@ -0,0 +1,64 @@
+export class ConversationManager {
+  constructor(steps, options = {}) {
+    this.steps = steps;
+    this.onComplete = options.onComplete;
+    this.onCancel = options.onCancel;
+    this.currentStep = 0;
+    this.data = {};
+    this.active = false;
+  }
+
+  get isActive() {
+    return this.active;
+  }
+
+  start() {
+    this.currentStep = 0;
+    this.data = {};
+    this.active = true;
+    const step = this.steps[0];
+    return `${step.prompt}${step.required ? '' : ` (/skip for ${step.default})`}`;
+  }
+
+  async handle(text, reply) {
+    if (!this.active) return false;
+
+    if (text === '/cancel') {
+      this.active = false;
+      this.data = {};
+      await (this.onCancel ? this.onCancel(reply) : reply('Cancelled.'));
+      return true;
+    }
+
+    const step = this.steps[this.currentStep];
+
+    if (text === '/skip') {
+      if (step.required) {
+        await reply(`This field is required. ${step.prompt}`);
+        return true;
+      }
+      this.data[step.field] = step.default;
+    } else {
+      if (step.validate) {
+        const error = step.validate(text);
+        if (error) {
+          await reply(`${error}\n${step.prompt}`);
+          return true;
+        }
+      }
+      this.data[step.field] = step.transform ? step.transform(text) : text;
+    }
+
+    this.currentStep++;
+
+    if (this.currentStep >= this.steps.length) {
+      this.active = false;
+      if (this.onComplete) await this.onComplete(this.data, reply);
+      return true;
+    }
+
+    const nextStep = this.steps[this.currentStep];
+    await reply(`${nextStep.prompt}${nextStep.required ? '' : ` (/skip for ${nextStep.default})`}`);
+    return true;
+  }
+}

package/src/features/ratelimit/RateLimiter.js

@@ -0,0 +1,38 @@
+export class RateLimiter {
+  constructor(options = {}) {
+    this.maxRequests = options.maxRequests || 3;
+    this.windowMs = options.windowMs || 24 * 60 * 60 * 1000;
+    this.usage = new Map();
+  }
+
+  check(identifier) {
+    const now = Date.now();
+    const entry = this.usage.get(identifier);
+
+    if (!entry || now >= entry.resetAt) {
+      return { allowed: true, remaining: this.maxRequests };
+    }
+
+    if (entry.count >= this.maxRequests) {
+      const msLeft = entry.resetAt - now;
+      return {
+        allowed: false,
+        remaining: 0,
+        resetIn: `${Math.floor(msLeft / 3600000)}h ${Math.ceil((msLeft % 3600000) / 60000)}m`
+      };
+    }
+
+    return { allowed: true, remaining: this.maxRequests - entry.count };
+  }
+
+  increment(identifier) {
+    const now = Date.now();
+    const entry = this.usage.get(identifier);
+
+    if (!entry || now >= entry.resetAt) {
+      this.usage.set(identifier, { count: 1, resetAt: now + this.windowMs });
+    } else {
+      entry.count++;
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+export { Messenger } from './core/Messenger.js';
+export { telegram, TelegramAdapter } from './platforms/telegram/index.js';
+export { ConversationManager } from './features/conversation/ConversationManager.js';
+export { RateLimiter } from './features/ratelimit/RateLimiter.js';
+export { createLogger } from './utils/logger.js';

package/src/platforms/telegram/TelegramAdapter.js

@@ -0,0 +1,104 @@
+import { PlatformAdapter } from '../../core/PlatformAdapter.js';
+import { readFile } from 'fs/promises';
+import { TelegramReceiver } from './TelegramReceiver.js';
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('telegram');
+
+export class TelegramAdapter extends PlatformAdapter {
+  constructor(config) {
+    super(config);
+    this.baseUrl = `https://api.telegram.org/bot${config.token}`;
+  }
+
+  validateConfig() {
+    if (!this.config.token) throw new Error('Token required');
+    if (!this.config.chatId && !this.config.allowDynamicRecipients) {
+      throw new Error('chatId required (or set allowDynamicRecipients: true)');
+    }
+  }
+
+  getRecipientId(recipient) {
+    return recipient || this.config.chatId;
+  }
+
+  async sendText(recipient, text, options = {}) {
+    const chatId = this.getRecipientId(recipient);
+    try {
+      const res = await fetch(`${this.baseUrl}/sendMessage`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          chat_id: chatId,
+          text,
+          parse_mode: options.parseMode || this.config.parseMode || 'Markdown'
+        })
+      });
+
+      const result = await res.json();
+      if (!result.ok) throw new Error(result.description);
+      return { status: 'success', messageId: result.result.message_id };
+    } catch (err) {
+      logger.error(`sendText failed: ${err.message}`);
+      return { status: 'failed', error: err.message };
+    }
+  }
+
+  async sendFile(recipient, filePath, options = {}) {
+    const chatId = this.getRecipientId(recipient);
+    try {
+      const form = new FormData();
+      form.append('chat_id', chatId);
+      form.append('document', new Blob([await readFile(filePath)]), options.fileName || filePath.split('/').pop());
+      if (options.caption) form.append('caption', options.caption);
+
+      const res = await fetch(`${this.baseUrl}/sendDocument`, { method: 'POST', body: form });
+      const result = await res.json();
+      if (!result.ok) throw new Error(result.description);
+      return { status: 'success', messageId: result.result.message_id };
+    } catch (err) {
+      logger.error(`sendFile failed: ${err.message}`);
+      return { status: 'failed', error: err.message };
+    }
+  }
+
+  async sendImage(recipient, imagePath, options = {}) {
+    const chatId = this.getRecipientId(recipient);
+    try {
+      const form = new FormData();
+      form.append('chat_id', chatId);
+      form.append('photo', new Blob([await readFile(imagePath)]), options.fileName || imagePath.split('/').pop());
+      if (options.caption) form.append('caption', options.caption);
+
+      const res = await fetch(`${this.baseUrl}/sendPhoto`, { method: 'POST', body: form });
+      const result = await res.json();
+      if (!result.ok) throw new Error(result.description);
+      return { status: 'success', messageId: result.result.message_id };
+    } catch (err) {
+      logger.error(`sendImage failed: ${err.message}`);
+      return { status: 'failed', error: err.message };
+    }
+  }
+
+  getReceiverClass() {
+    return TelegramReceiver;
+  }
+
+  async healthCheck() {
+    try {
+      const res = await fetch(`${this.baseUrl}/getMe`);
+      const result = await res.json();
+      if (!result.ok) return { status: 'error', error: result.description };
+      return {
+        status: 'ok',
+        bot: {
+          id: result.result.id,
+          username: result.result.username,
+          firstName: result.result.first_name
+        }
+      };
+    } catch (err) {
+      return { status: 'error', error: err.message };
+    }
+  }
+}

package/src/platforms/telegram/TelegramReceiver.js

@@ -0,0 +1,98 @@
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('telegram');
+
+export class TelegramReceiver {
+  constructor(adapter, messenger) {
+    this.adapter = adapter;
+    this.messenger = messenger;
+    this.offset = 0;
+    this.running = false;
+    this.pollTimeout = adapter.config.pollTimeout || 30;
+    this.allowedChatIds = this.parseAllowedChatIds();
+  }
+
+  parseAllowedChatIds() {
+    const { allowedChatIds } = this.adapter.config;
+    if (!allowedChatIds) return null;
+    if (Array.isArray(allowedChatIds)) return allowedChatIds.map(Number);
+    return allowedChatIds.split(',').map(id => Number(id.trim()));
+  }
+
+  isAllowed(chatId) {
+    return !this.allowedChatIds || this.allowedChatIds.includes(chatId);
+  }
+
+  async getUpdates() {
+    try {
+      const res = await fetch(`${this.adapter.baseUrl}/getUpdates`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ offset: this.offset, timeout: this.pollTimeout })
+      });
+      const result = await res.json();
+      if (!result.ok) throw new Error(result.description);
+      return result.result || [];
+    } catch (err) {
+      logger.error(`getUpdates failed: ${err.message}`);
+      return [];
+    }
+  }
+
+  async handleUpdate(update) {
+    const message = update.message;
+    if (!message?.text) return;
+
+    const chatId = message.chat.id;
+    if (!this.isAllowed(chatId)) return;
+
+    const text = message.text.trim();
+    const context = {
+      chatId,
+      userId: message.from.id,
+      message: text,
+      raw: update,
+      reply: async (msg) => await this.adapter.sendText(chatId, msg),
+      messenger: this.messenger
+    };
+
+    const conversation = this.messenger.conversation(chatId);
+    if (conversation?.isActive) {
+      await conversation.handle(text, context.reply);
+      if (!conversation.isActive) this.messenger.clearConversation(chatId);
+      return;
+    }
+
+    if (text.startsWith('/')) {
+      const handled = await this.messenger.handleCommand(text, context);
+      if (!handled) await context.reply(`Unknown command: ${text.split(' ')[0]}`);
+      return;
+    }
+
+    await this.messenger.handleMessage(context);
+  }
+
+  async start() {
+    if (this.running) return;
+    this.running = true;
+    logger.info('Polling started');
+
+    while (this.running) {
+      try {
+        const updates = await this.getUpdates();
+        for (const update of updates) {
+          this.offset = update.update_id + 1;
+          await this.handleUpdate(update);
+        }
+      } catch (err) {
+        logger.error(`Polling error: ${err.message}`);
+        await new Promise(resolve => setTimeout(resolve, 5000));
+      }
+    }
+  }
+
+  async stop() {
+    this.running = false;
+    logger.info('Polling stopped');
+  }
+}

package/src/platforms/telegram/index.js

@@ -0,0 +1,8 @@
+import { TelegramAdapter } from './TelegramAdapter.js';
+
+export function telegram(config) {
+  return new TelegramAdapter(config);
+}
+
+export { TelegramAdapter } from './TelegramAdapter.js';
+export { TelegramReceiver } from './TelegramReceiver.js';

package/src/utils/logger.js

@@ -0,0 +1,10 @@
+import { Logger } from 'logger-standard';
+
+export const createLogger = (service) => {
+  return new Logger({
+    service,
+    showDate: process.env.LOG_SHOW_DATE === 'true'
+  });
+};
+
+export const logger = createLogger('messenger');