add-telegram-update-field

name	add-telegram-update-field
description	[Library contributor] Adds a new field to the Update type and wires it through ProcessedUpdate, UpdateType, ProcessUpdate, KSP (TypeConstants, TypeMapper), and FunctionalDSLUtils. Use when implementing support for a new Telegram update type (e.g. message_reaction, chat_boost), adding a new update handler, or extending the bot to handle additional update kinds.

Add Telegram Update Field

Workflow

1. Add Field to Update

• In Update.kt: add val myField: MyType? = null (camelCase, nullable)
• Add import for the payload type if needed

2. Add UpdateType Entry

• In UpdateType.kt: add enum entry with @SerialName("snake_case") matching Telegram API (e.g. MY_FIELD)

3. Add ProcessedUpdate Subclass

• In ProcessedUpdate.kt: add data class MyFieldUpdate(...) : ProcessedUpdate(...)
• Use @Serializable(MyFieldUpdate.Companion::class) and internal companion object : UpdateSerializer<MyFieldUpdate>()
• Implement UserReference when the update has a user; ChatReference when it has a chat; TextReference when it has text

4. Add processUpdate Clause

• In ProcessUpdate.kt: add myField != null -> MyFieldUpdate(updateId, this, myField)
• Add import for the new ProcessedUpdate subclass
• Place clause in a logical order (group with similar update types)

5. Update KSP Module

• In TypeConstants.kt: add val myFieldUpdateClass: TypeName = MyFieldUpdate::class.asTypeName()
• In TypeMapper.kt: add TypeConstants.myFieldUpdateClass to MyFieldUpdate::class to updateTypeMap

6. Regenerate FunctionalDSLUtils

• Run ./gradlew prepareRelease (or full build)
• api-sentinel KSP regenerates FunctionalDSLUtils.kt from UpdateType.entries; no manual edits needed

Handling: The new onXxx DSL function enables bot.setFunctionality { onXxx { ... } }. Both functional DSL and annotation approach (@UpdateHandler) use the same ActivityRegistry and ProcessingPipeline; see telegram-bot-handling.mdc.

Naming Conventions

• Update field: camelCase (e.g. callbackQuery, messageReaction)
• UpdateType: SCREAMING_SNAKE_CASE, @SerialName("snake_case") matching Telegram API
• ProcessedUpdate subclass: XxxUpdate (e.g. CallbackQueryUpdate)

Reference Examples

• MessageUpdate - UserReference + ChatReference
• PollUpdate - minimal, no User/Chat
• CallbackQueryUpdate - UserReference + ChatReference

Validation

./gradlew formatKotlin
./gradlew prepareRelease