code comments and readme updates (#2)

Author: wkande

README.md

@@ -1,4 +1,16 @@
-# @api3/discord-bot
+# api3-telegram-bot
+
+There are two Api3 groups in Telegram. In Telegram a group is sometime called a chat or chat group.
+
+- Api3 - public with invite URL
+- Api3 Administrators - private
+
+This bot drives AI processing of Telegram messages. The AI prompt determines if a message violates the Api3 group rules. The rules are publicly available, the AI prompt is not. Other features include keyboard actions in the Api3 Administrators group for the following:
+
+- Timeout 24 hours
+- Timeout forever
+- Clear timeout
+- Restore message
 
 ## Documentation
 

src/actions.js

@@ -1,10 +1,6 @@
-/*
-
-https://hackage.haskell.org/package/telegram-bot-api-7.4.4/docs/Telegram-Bot-API-Methods-RestrictChatMember.html
-Date when restrictions will be lifted for the user, unix time. If user is restricted for more 
-than 366 days or less than 30 seconds from the current time, 
-they are considered to be restricted forever.
-
+/**
+ * Actions (keyboard actions) are only available on a per message basis in the group Api3
+ * Administrators which is a private group with a few manually added admins.
  */
 
 const { bot } = require('./bot');
@@ -14,7 +10,7 @@ const { PERMISSIONS_TIMEOUT } = require('./permissions');
 const CONFIG = JSON.parse(fs.readFileSync('./config.json', 'utf-8'))[process.env.NODE_ENV];
 
 /**
- * Timeout 24 hours
+ * Timeout a user for 24 hours.
  * @param {*} bot
  */
 async function startActionTimeout24() {
@@ -51,7 +47,7 @@ async function startActionTimeout24() {
 }
 
 /**
- * Timeout forever
+ * Timeout a user forever.
  * @param {*} bot
  */
 async function startActionTimeoutForever() {
@@ -87,7 +83,7 @@ async function startActionTimeoutForever() {
 }
 
 /**
- * Clear timeout
+ * Clears any timeout that may have been applied to a user.
  * @param {*} bot
  */
 async function startActionTimeoutClear() {
@@ -124,7 +120,7 @@ async function startActionTimeoutClear() {
 }
 
 /**
- * Restore message
+ * Restore message from disk storage. Any timeout applied to the user is removed.
  * @param {*} bot
  */
 async function startActionRestoreMessage() {
@@ -165,6 +161,13 @@ async function startActionRestoreMessage() {
   });
 }
 
+/**
+ * Gets a message that has been stored on disk for a max of 7.1 days.
+ * @param {*} ctx
+ * @param {*} action
+ * @param {*} msgId
+ * @returns
+ */
 async function getMessageFromDisk(ctx, action, msgId) {
   try {
     return JSON.parse(fs.readFileSync(`../telegram-messages/${msgId}.json`));

src/bot.js

@@ -1,3 +1,10 @@
+/**
+ * This file creates the bot for other files to use including setting the bot options such
+ * actions. The bot is exported.
+ *
+ * It also purges messages that are stored on disk once they exceed 7.1 days in age.
+ */
+
 const { Telegraf } = require('telegraf');
 const fs = require('fs');
 const path = require('path');
@@ -7,7 +14,7 @@ const CONFIG = JSON.parse(fs.readFileSync('./config.json', 'utf-8'))[process.env
 let bot = undefined;
 
 if (!bot) {
-  // Initialize bot with bot token, bot is used to talk to the Telegram API via Telegraf
+  // Initialize bot with bot token, bot is used to talk to the Telegram API via Telegraf.
   bot = new Telegraf(CONFIG.token);
   console.info('The bot is ready.');
 }
@@ -36,7 +43,7 @@ setInterval(function () {
   } catch (err) {
     console.error('Error reading directory:', err);
   }
-}, 3.6e6); // Executes every hour
+}, 3.6e6); // Interval executes every hour
 
 module.exports = {
   bot

src/handlers.js

@@ -1,6 +1,14 @@
 const { chat } = require('./llm');
 const fs = require('fs');
 
+/**
+ * Returns the opinion of an AI openrouter model for a message passed. The call from here
+ * continues onto the llm.js file function chat(messages).
+ *
+ * Example usage: const returnedArray = await handleMessage(ctx.update.message.text);
+ * @param {*} message
+ * @returns
+ */
 const handleMessage = async (message) => {
   // Get the prompt
   const prompt = fs.readFileSync('./prompt.txt', 'utf-8');