✨ tweak: Add docstrings to dev - Merge pull request #8 from wgtechlabs/coderabbitai/docstrings/rBEa

Author: warengonzaga

src/bot.ts

@@ -12,10 +12,11 @@ import { BotsStore } from './sdk/bots-brain/index.js';
 import { BotContext, TelegramError, CommandHandler } from './types/index.js';
 
 /**
- * Creates a new Telegram bot instance
- * 
- * @param token - The Telegram Bot API token
- * @returns A new Telegraf bot instance
+ * Creates and returns a new Telegraf bot instance using the provided Telegram Bot API token.
+ *
+ * @param token - The Telegram Bot API token to authenticate the bot
+ * @returns The initialized Telegraf bot instance
+ * @throws If the token is missing or empty
  */
 export function createBot(token: string): Telegraf<BotContext> {
     if (!token) {
@@ -25,10 +26,9 @@ export function createBot(token: string): Telegraf<BotContext> {
 }
 
 /**
- * Configures the bot's command handlers
- * 
- * @param bot - The Telegraf bot instance
- * @param commands - Array of command objects with name and handler
+ * Registers command handlers on the bot for each specified command.
+ *
+ * @param commands - List of command definitions, each containing a command name and its handler function.
  */
 export function configureCommands(
     bot: Telegraf<BotContext>, 
@@ -40,22 +40,23 @@ export function configureCommands(
 }
 
 /**
- * Starts the bot polling for updates
- * 
- * @param bot - The Telegraf bot instance
+ * Starts the bot's polling mechanism to receive updates from Telegram.
+ *
+ * Initiates the process for the bot to listen for and handle incoming messages and events.
  */
 export function startPolling(bot: Telegraf<BotContext>): void {
     bot.launch();
 }
 
 /**
- * Safely send a message with error handling for blocked users and other common errors
- * 
- * @param bot - The Telegraf bot instance
- * @param chatId - The chat ID to send the message to
- * @param text - The message text
- * @param options - Additional options for sendMessage
- * @returns The sent message object or null if failed
+ * Sends a message to a specified chat, handling common Telegram errors such as blocked users, chat not found, and rate limits.
+ *
+ * Attempts to send a message and performs cleanup if the bot is blocked or the chat does not exist. Returns null if sending fails due to these conditions or rate limiting; otherwise, returns the sent message object.
+ *
+ * @param chatId - The target chat ID
+ * @param text - The message text to send
+ * @param options - Optional parameters for message formatting and behavior
+ * @returns The sent message object, or null if the message could not be delivered due to blocking, chat not found, or rate limiting
  */
 export async function safeSendMessage(
     bot: Telegraf<BotContext>, 
@@ -106,12 +107,14 @@ export async function safeSendMessage(
 }
 
 /**
- * Safely reply to a message with cleanup handling for blocked users
- * 
- * @param ctx - The Telegraf context object
- * @param text - The message text to reply with
- * @param options - Additional options for the reply
- * @returns The sent message object or null if failed
+ * Replies to a message in the given context, handling errors such as blocked users, missing chats, and rate limits.
+ *
+ * If the bot is blocked or the chat is not found, associated user data is cleaned up and null is returned. If rate limits are exceeded, a warning is logged and null is returned. Other errors are logged and re-thrown.
+ *
+ * @param ctx - The Telegraf context for the incoming message
+ * @param text - The reply message text
+ * @param options - Optional parameters for the reply
+ * @returns The sent message object, or null if the reply could not be sent due to blocking, missing chat, or rate limiting
  */
 export async function safeReply(
     ctx: BotContext, 
@@ -170,15 +173,17 @@ export async function safeReply(
 }
 
 /**
- * Safely edit a message text with cleanup handling for blocked users
- * 
+ * Attempts to edit the text of a Telegram message, handling common errors such as blocked users, missing chats, rate limits, and non-critical edit failures.
+ *
+ * If the bot is blocked or the chat is not found, associated user data is cleaned up and `null` is returned. Rate limit errors also result in `null`. If the message is not found or already modified, the error is logged and `null` is returned. Other errors are logged and re-thrown.
+ *
  * @param ctx - The Telegraf context object
- * @param chatId - The chat ID
- * @param messageId - The message ID to edit
- * @param inlineMessageId - Inline message ID (if applicable)
- * @param text - The new message text
- * @param options - Additional options for editing
- * @returns The edited message object or null if failed
+ * @param chatId - The target chat ID
+ * @param messageId - The ID of the message to edit
+ * @param inlineMessageId - The inline message ID, if applicable
+ * @param text - The new text for the message
+ * @param options - Additional options for editing the message
+ * @returns The edited message object, or `null` if the operation fails due to handled errors
  */
 export async function safeEditMessageText(
     ctx: BotContext, 
@@ -248,10 +253,11 @@ export async function safeEditMessageText(
 }
 
 /**
- * Clean up user data when bot is blocked or chat is not found
- * This implements the fix from GitHub issue telegraf/telegraf#1513
- * 
- * @param chatId - The chat ID of the blocked user
+ * Cleans up all local data associated with a chat when the bot is blocked or the chat is not found.
+ *
+ * Removes tickets and customer mappings related to the specified chat from persistent storage. User state data is not explicitly removed but will expire automatically. Errors during cleanup are logged but do not interrupt bot operation.
+ *
+ * @param chatId - The Telegram chat ID to clean up data for
  */
 async function cleanupBlockedUser(chatId: number): Promise<void> {
     try {

src/commands/index.ts

@@ -520,7 +520,9 @@ export const processSupportConversation = async (ctx: BotContext): Promise<boole
 };
 
 /**
- * Handles the email field input and completes the ticket process
+ * Processes the email input step of the support ticket conversation and completes ticket creation.
+ *
+ * If the user enters "skip", an auto-generated email is used. The function then finalizes the ticket by interacting with external services to create the customer, user, and ticket records, updates the user with confirmation or error messages, and clears the user's conversation state.
  */
 async function handleEmailField(ctx: BotContext, userState: any, messageText: string): Promise<void> {
     try {

src/events/message.ts

@@ -13,24 +13,27 @@ import { safeReply, safeEditMessageText } from '../bot.js';
 import type { BotContext } from '../types/index.js';
 
 /**
- * Checks if a message is from a group chat (not a channel)
+ * Returns true if the message originates from a group or supergroup chat.
+ *
+ * @returns True if the chat type is 'group' or 'supergroup'; otherwise, false.
  */
 export function isGroupChat(ctx: BotContext): boolean {
     return ctx.chat?.type === 'group' || ctx.chat?.type === 'supergroup';
 }
 
 /**
- * Checks if a message is from a private chat
+ * Determines whether the current chat is a private chat.
+ *
+ * @returns True if the chat type is 'private'; otherwise, false.
  */
 export function isPrivateChat(ctx: BotContext): boolean {
     return ctx.chat?.type === 'private';
 }
 
 /**
- * Handles all incoming messages
- * 
- * This function routes messages to appropriate handlers based on chat type
- * and processes text messages against registered patterns
+ * Main handler for incoming Telegram messages, routing them to appropriate processors based on chat type and message context.
+ *
+ * Determines whether to process the message as a command, support conversation, ticket reply, private chat, or group chat, and delegates handling accordingly. Prevents automatic responses in group chats and ensures that only relevant handlers are invoked for each message type.
  */
 export async function handleMessage(ctx: BotContext, next: () => Promise<void>): Promise<void> {
     try {
@@ -100,7 +103,11 @@ export async function handleMessage(ctx: BotContext, next: () => Promise<void>):
 }
 
 /**
- * Handles replies to ticket confirmation messages
+ * Processes replies to ticket confirmation or agent messages and routes them for handling.
+ *
+ * Checks if the incoming message is a reply to a ticket confirmation or agent message, and if so, processes the reply accordingly. Returns true if the reply was handled, or false otherwise.
+ *
+ * @returns True if the reply was processed as a ticket or agent message reply; false otherwise.
  */
 async function handleTicketReply(ctx: BotContext): Promise<boolean> {
     try {
@@ -157,7 +164,11 @@ async function handleTicketReply(ctx: BotContext): Promise<boolean> {
 }
 
 /**
- * Handles replies to ticket confirmation messages
+ * Processes a reply to a ticket confirmation message by validating the reply, sending the message to the ticket conversation, and updating the user with a status message.
+ *
+ * @param ctx - The Telegram bot context for the incoming message
+ * @param ticketInfo - Information about the ticket to which the reply is associated
+ * @returns True if the reply was processed (successfully or with an error status message), or false if validation failed or an unexpected error occurred
  */
 async function handleTicketConfirmationReply(ctx: BotContext, ticketInfo: any): Promise<boolean> {
     try {
@@ -214,7 +225,9 @@ async function handleTicketConfirmationReply(ctx: BotContext, ticketInfo: any):
 }
 
 /**
- * Validates the reply context and ticket information
+ * Validates that the reply message and sender information are present and extracts user and message details for ticket processing.
+ *
+ * @returns An object indicating whether the reply is valid. If valid, includes the sender's Telegram user ID, username, and message text.
  */
 async function validateTicketReply(ctx: BotContext, ticketInfo: any): Promise<{ isValid: false } | { isValid: true; telegramUserId: number; username: string | undefined; message: string }> {
     if (!ctx.from || !ctx.message || !('text' in ctx.message)) {
@@ -243,7 +256,9 @@ async function validateTicketReply(ctx: BotContext, ticketInfo: any): Promise<{
 }
 
 /**
- * Processes and sends the ticket message to Unthread
+ * Sends a user's message to the specified ticket conversation in Unthread.
+ *
+ * Retrieves or creates user data based on the Telegram user ID and username, then sends the provided message to the ticket conversation identified by the ticket information.
  */
 async function processTicketMessage(ticketInfo: any, telegramUserId: number, username: string | undefined, message: string): Promise<void> {
     // Get user information from database
@@ -272,7 +287,9 @@ async function processTicketMessage(ticketInfo: any, telegramUserId: number, use
 }
 
 /**
- * Updates the status message and handles cleanup
+ * Updates a status message to indicate success or error, then deletes it after a short delay.
+ *
+ * The message is updated to show a checkmark for success or an error icon for failure, and is automatically removed after 3 seconds (success) or 5 seconds (error).
  */
 async function updateStatusMessage(ctx: BotContext, statusMsg: any, isSuccess: boolean): Promise<void> {
     if (isSuccess) {
@@ -307,7 +324,11 @@ async function updateStatusMessage(ctx: BotContext, statusMsg: any, isSuccess: b
 }
 
 /**
- * Handles replies to agent messages
+ * Processes a user's reply to an agent message by forwarding it to the corresponding Unthread conversation.
+ *
+ * Sends a status message indicating progress, updates it upon success or error, and deletes the status message after a delay. Returns true if the reply was processed, false otherwise.
+ *
+ * @returns True if the reply was handled (successfully sent or error occurred), false if the context was invalid.
  */
 async function handleAgentMessageReply(ctx: BotContext, agentMessageInfo: any): Promise<boolean> {
     try {
@@ -400,7 +421,9 @@ async function handleAgentMessageReply(ctx: BotContext, agentMessageInfo: any):
 }
 
 /**
- * Handles messages from private chats (direct messages to the bot)
+ * Processes incoming messages from private chats and responds with an about message for non-command texts.
+ *
+ * Skips messages that are commands, allowing them to be handled by their respective handlers.
  */
 export async function handlePrivateMessage(ctx: BotContext): Promise<void> {
     try {
@@ -438,7 +461,9 @@ export async function handlePrivateMessage(ctx: BotContext): Promise<void> {
 }
 
 /**
- * Handles messages from group chats
+ * Processes incoming messages from group chats without sending automatic responses.
+ *
+ * Logs detailed information about the group, sender, and message content for monitoring and debugging purposes.
  */
 export async function handleGroupMessage(ctx: BotContext): Promise<void> {
     try {

src/index.ts

@@ -193,7 +193,17 @@ bot.on('callback_query', async (ctx) => {
 });
 
 /**
- * Retry helper function with exponential backoff
+ * Executes an asynchronous operation with retries and exponential backoff on failure.
+ *
+ * Retries the provided async operation up to a specified number of times, increasing the delay between attempts exponentially up to a maximum delay. Logs warnings on each retry and an error if all attempts fail.
+ *
+ * @param operation - The asynchronous function to execute and retry on failure
+ * @param maxRetries - Maximum number of retry attempts (default: 5)
+ * @param initialDelayMs - Initial delay in milliseconds before the first retry (default: 1000)
+ * @param maxDelayMs - Maximum delay in milliseconds between retries (default: 30000)
+ * @param operationName - Name used in log messages to identify the operation (default: 'operation')
+ * @returns The result of the successful operation
+ * @throws The last encountered error if all retries fail
  */
 async function retryWithBackoff<T>(
     operation: () => Promise<T>,
@@ -421,11 +431,11 @@ bot.catch(async (error: any, ctx?: BotContext) => {
 });
 
 /**
- * Clean up user data when bot is blocked or chat is not found
- * This implements the fix from GitHub issue telegraf/telegraf#1513
- * Global version for use in error handlers
- * 
- * @param chatId - The chat ID of the blocked user
+ * Removes all tickets and customer mappings associated with a Telegram chat when the bot is blocked or the chat is not found.
+ *
+ * Cleans up related tickets and customer data in storage for the specified chat ID. User state data is not explicitly removed but will expire automatically.
+ *
+ * @param chatId - The Telegram chat ID to clean up.
  */
 async function cleanupBlockedUserGlobal(chatId: number): Promise<void> {
     try {
@@ -485,9 +495,9 @@ async function cleanupBlockedUserGlobal(chatId: number): Promise<void> {
 }
 
 /**
- * Performs graceful shutdown of all services
- * 
- * Properly close database connections, stop webhook consumer, and stop the bot
+ * Shuts down all services and resources used by the bot, ensuring a clean exit.
+ *
+ * Stops the webhook consumer if running, shuts down the BotsStore, closes database connections, and exits the process. Logs each shutdown step and exits with an error code if any shutdown operation fails.
  */
 async function gracefulShutdown(): Promise<void> {
     try {