Telegram Bot API wrapper for Kotlin

To extend the library with a new type of Telegram Update, follow these steps to ensure the data flows correctly from the raw update through the processing logic and into the KSP-generated DSL:

1. Define the Data: Add a new field to the Update class in eu/vendeli/tgbot/types/common/Update.kt.
2. Define the Type: Add a new entry to the UpdateType enum in telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/component/UpdateType.kt.
3. Create the Processed Type: Create a new subclass of ProcessedUpdate in telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/types/component/ProcessedUpdate.kt.
4. Update Processing Logic: Add a new clause to the processUpdate() function in telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/utils/common/ProcessUpdate.kt.
5. Configure KSP (Code Generation):
   • Add a new TypeName constant to TypeConstants in ktnip/src/jvmMain/kotlin/eu/vendeli/ktnip/utils/TypeConstants.kt.
   • Add a corresponding mapping entry to TypeMapper in ktnip/src/jvmMain/kotlin/eu/vendeli/ktnip/codegen/TypeMapper.kt.
6. Update DSL: Run the helper KSP task to add the new section for FunctionalDSLUtils in telegram-bot/src/commonMain/kotlin/eu/vendeli/tgbot/utils/common/FunctionalDSLUtils.kt.

To use the library, you must instantiate the TelegramBot class. You can do this in three ways:

1. Directly with a token: Provide the bot token and an optional commandsPackage (where the bot will look for annotated commands).
2. Using a ConfigLoader: Pass a ConfigLoader instance to automatically load the token and configuration.
3. With a custom HttpClient: Provide your own Ktor HttpClient instance if you need to customize the underlying network layer.

You can also provide a BotConfigurator lambda to customize the BotConfiguration during initialization.

// 1. Basic initialization
val bot = TelegramBot(token = "YOUR_BOT_TOKEN")

// 2. Initialization with custom configuration
val bot = TelegramBot(token = "YOUR_BOT_TOKEN") { config ->
    // Customize config here
}

// 3. Initialization with a custom HttpClient
val bot = TelegramBot(
    token = "YOUR_BOT_TOKEN",
    httpClient = myCustomHttpClient
)

You can define bot logic using annotated functions. Common annotations include:

• @CommandHandler(commands: Array<String>): Responds to specific slash commands.
• @InputHandler(inputs: Array<String>): Responds to specific input states (useful for Finite State Machines).
• @CommonHandler.Regex(pattern: String): Responds to messages matching a regular expression.

You can use @Guard(guardClass: KClass<T>) to restrict access to a handler based on specific conditions.

To manage user states (Finite State Machine), use bot.inputListener[user] = "state_name" to transition a user to a specific input handler.

suspend fun main() {
    val bot = TelegramBot("BOT_TOKEN")
    bot.handleUpdates()
}

@CommandHandler(["/start"])
suspend fun start(user: User, bot: TelegramBot) {
    sendMessage { "Hello, what's your name?" }.send(user, bot)
    bot.inputListener[user] = "conversation"
}

@InputHandler(["conversation"])
@Guard(UserPresentGuard::class)
suspend fun startConversation(update: ProcessedUpdate, user: User, bot: TelegramBot) {
    sendMessage { "Nice to meet you, ${update.text}" }.send(user, bot)
    sendMessage { "What is your favorite food?" }.send(user, bot)

    bot.inputListener.set(user) { "conversation-2step" }
}

@CommonHandler.Regex("blue colo?r")
suspend fun color(user: User, bot: TelegramBot) {
    message { "Oh you also like blue color?" }.send(user, bot)
}

Instead of annotations, you can define bot behavior using a DSL within the bot.setFunctionality block. This allows for complex logic like inputChain, which defines a sequence of inputs, and breakIf, which allows you to interrupt a chain based on a condition.

inputChain supports .breakIf({ condition }) to handle specific user responses and .andThen { ... } to define what happens if the break condition is not met.

fun main() = runBlocking {
    val bot = TelegramBot("BOT_TOKEN")

    bot.setFunctionality {
        onCommand("/start") {
            message { "Hello, what's your name?" }.send(user, bot)
            bot.inputListener[user] = "conversation"
        }
        inputChain("conversation") {
            message { "Nice to meet you, ${message.text}" }.send(update.getUser(), bot)
            message { "What is your favorite food?" }.send(update.getUser(), bot)
        }.breakIf({ message.text == "peanut butter" }) {
            message { "Oh, too bad, I'm allergic to it." }.send(update.getUser(), bot)
        }.andThen {
            // next input point if break condition doesn't match
        }
    }
    
    bot.handleUpdates()
}

The BotConfiguration class is used to set up a Telegram bot within a Ktor application. It allows you to define the bot's authentication token, the package where commands are located, custom handling behaviors for updates, and initialization hooks.

Key properties:

• token: The unique Telegram bot token (must be provided).
• pckg: An optional string specifying the package where the bot should search for commands.

Available configuration methods:

• configuration(config: BotConfigurator): Sets the core bot configuration using a BotConfigurator lambda.
• handlingBehaviour(block: HandlingBehaviourBlock): Defines how updates are handled.
• onInit(block: suspend (bot: TelegramBot) -> Unit): Provides a hook to execute code immediately after the bot is initialized.

// Example usage within a Ktor configuration context
BotConfiguration().apply {
    token = "YOUR_BOT_TOKEN"
    pckg = "eu.vendeli.myapp.commands"
    
    configuration { 
        // Configure using BotConfigurator
    }

    handlingBehaviour { 
        // Define handling behavior
    }

    onInit { bot ->
        // Perform actions after bot initialization
        println("Bot initialized: ${bot.name}")
    }
}

The EnvConfiguration implementation allows you to configure the server using environment variables prefixed with KTGRAM_.

Required variables must be provided, or the application will throw an ApplicationConfigurationException. Some variables have default values if not specified.