add-telegram-update-field - SKILL.md Agent Skill

name: add-telegram-update-field description: 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