telegram-bot-ruby 2.8.1 → 2.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (95) hide show
  1. checksums.yaml +4 -4
  2. data/.agents/skills/commit/SKILL.md +18 -0
  3. data/.agents/skills/update-api/SKILL.md +70 -0
  4. data/.claude/skills +1 -0
  5. data/.rubocop.yml +0 -14
  6. data/CHANGELOG.md +16 -0
  7. data/README.md +16 -2
  8. data/lib/telegram/bot/api/endpoints.rb +9 -0
  9. data/lib/telegram/bot/types/area_position.rb +16 -0
  10. data/lib/telegram/bot/types/chat_administrator_rights.rb +1 -0
  11. data/lib/telegram/bot/types/chat_full_info.rb +2 -0
  12. data/lib/telegram/bot/types/chat_member_administrator.rb +1 -0
  13. data/lib/telegram/bot/types/chat_share_theme.rb +15 -0
  14. data/lib/telegram/bot/types/chat_share_theme_backdrop.rb +13 -0
  15. data/lib/telegram/bot/types/chat_share_theme_backdrops.rb +11 -0
  16. data/lib/telegram/bot/types/chat_share_theme_emoji.rb +13 -0
  17. data/lib/telegram/bot/types/chat_share_theme_unique_gift.rb +12 -0
  18. data/lib/telegram/bot/types/community_chat_joined.rb +11 -0
  19. data/lib/telegram/bot/types/disabled_button.rb +10 -0
  20. data/lib/telegram/bot/types/emoji_type.rb +15 -0
  21. data/lib/telegram/bot/types/emoji_type_custom_emoji.rb +12 -0
  22. data/lib/telegram/bot/types/emoji_type_emoji.rb +12 -0
  23. data/lib/telegram/bot/types/ephemeral_message_parameters.rb +13 -0
  24. data/lib/telegram/bot/types/external_reply_info.rb +1 -0
  25. data/lib/telegram/bot/types/game.rb +1 -1
  26. data/lib/telegram/bot/types/inline_keyboard_button.rb +1 -0
  27. data/lib/telegram/bot/types/inline_keyboard_markup.rb +1 -0
  28. data/lib/telegram/bot/types/input_checklist.rb +1 -1
  29. data/lib/telegram/bot/types/input_checklist_task.rb +1 -1
  30. data/lib/telegram/bot/types/input_message_content.rb +3 -1
  31. data/lib/telegram/bot/types/input_rich_block.rb +3 -0
  32. data/lib/telegram/bot/types/input_rich_block_buttons.rb +13 -0
  33. data/lib/telegram/bot/types/input_rich_block_document.rb +13 -0
  34. data/lib/telegram/bot/types/input_rich_block_expandable_block_quotation.rb +13 -0
  35. data/lib/telegram/bot/types/input_rich_block_map.rb +3 -3
  36. data/lib/telegram/bot/types/input_rich_block_table.rb +1 -0
  37. data/lib/telegram/bot/types/input_rich_message_media.rb +2 -1
  38. data/lib/telegram/bot/types/input_shared_widget_message_content.rb +16 -0
  39. data/lib/telegram/bot/types/input_widget_message_content.rb +21 -0
  40. data/lib/telegram/bot/types/message.rb +4 -0
  41. data/lib/telegram/bot/types/message_generation_stopped.rb +13 -0
  42. data/lib/telegram/bot/types/paid_messages_waived.rb +10 -0
  43. data/lib/telegram/bot/types/poll.rb +1 -1
  44. data/lib/telegram/bot/types/reply_keyboard_markup.rb +1 -0
  45. data/lib/telegram/bot/types/reply_parameters.rb +1 -0
  46. data/lib/telegram/bot/types/rich_block.rb +3 -0
  47. data/lib/telegram/bot/types/rich_block_buttons.rb +13 -0
  48. data/lib/telegram/bot/types/rich_block_document.rb +13 -0
  49. data/lib/telegram/bot/types/rich_block_expandable_block_quotation.rb +13 -0
  50. data/lib/telegram/bot/types/rich_block_table.rb +1 -0
  51. data/lib/telegram/bot/types/rich_message_button.rb +21 -0
  52. data/lib/telegram/bot/types/rich_text.rb +2 -0
  53. data/lib/telegram/bot/types/rich_text_button.rb +12 -0
  54. data/lib/telegram/bot/types/rich_text_ton_address.rb +13 -0
  55. data/lib/telegram/bot/types/shared_widget_query.rb +15 -0
  56. data/lib/telegram/bot/types/story_area.rb +1 -1
  57. data/lib/telegram/bot/types/text_quote.rb +1 -0
  58. data/lib/telegram/bot/types/ton_nft.rb +17 -0
  59. data/lib/telegram/bot/types/ton_nft_attribute.rb +12 -0
  60. data/lib/telegram/bot/types/ton_wallet_card.rb +14 -0
  61. data/lib/telegram/bot/types/ton_wallet_card_sticker.rb +12 -0
  62. data/lib/telegram/bot/types/ton_wallet_transfer.rb +14 -0
  63. data/lib/telegram/bot/types/unique_gift_info.rb +3 -0
  64. data/lib/telegram/bot/types/update.rb +3 -0
  65. data/lib/telegram/bot/types/widget.rb +16 -0
  66. data/lib/telegram/bot/types/widget_query.rb +20 -0
  67. data/lib/telegram/bot/types/widget_query_type.rb +16 -0
  68. data/lib/telegram/bot/types/widget_query_type_data.rb +12 -0
  69. data/lib/telegram/bot/types/widget_query_type_sent_transaction.rb +13 -0
  70. data/lib/telegram/bot/types/widget_query_type_sign_data.rb +13 -0
  71. data/lib/telegram/bot/types/widget_query_wallet.rb +14 -0
  72. data/lib/telegram/bot/version.rb +1 -1
  73. data/rakelib/README.md +116 -0
  74. data/rakelib/builders/type_builder.rb +3 -4
  75. data/rakelib/docs.rake +15 -0
  76. data/rakelib/parse.rake +8 -25
  77. data/rakelib/parsers/api_method.rb +26 -0
  78. data/rakelib/parsers/description.rb +62 -0
  79. data/rakelib/parsers/docs_page.rb +62 -0
  80. data/rakelib/parsers/entry.rb +45 -0
  81. data/rakelib/parsers/entry_grammar.rb +48 -0
  82. data/rakelib/parsers/error.rb +5 -0
  83. data/rakelib/parsers/field.rb +30 -0
  84. data/rakelib/parsers/object_type.rb +29 -0
  85. data/rakelib/parsers/page_object.rb +41 -0
  86. data/rakelib/parsers/readers.rb +16 -0
  87. data/rakelib/parsers/return_type.rb +36 -0
  88. data/rakelib/parsers/serializer.rb +93 -0
  89. data/rakelib/parsers/table.rb +14 -0
  90. data/rakelib/parsers/type_ref.rb +42 -0
  91. data/rakelib/parsers/union_type.rb +42 -0
  92. metadata +60 -5
  93. data/.claude/skills/update-api/SKILL.md +0 -70
  94. data/rakelib/parsers/methods_parser.rb +0 -115
  95. data/rakelib/parsers/types_parser.rb +0 -283
@@ -54,6 +54,7 @@ module Telegram
54
54
  attribute? :video, Video
55
55
  attribute? :video_note, VideoNote
56
56
  attribute? :voice, Voice
57
+ attribute? :widget, Widget
57
58
  attribute? :caption, Types::String
58
59
  attribute? :caption_entities, Types::Array.of(MessageEntity)
59
60
  attribute? :show_caption_above_media, Types::True
@@ -96,6 +97,7 @@ module Telegram
96
97
  attribute? :checklist_tasks_done, ChecklistTasksDone
97
98
  attribute? :checklist_tasks_added, ChecklistTasksAdded
98
99
  attribute? :community_chat_added, CommunityChatAdded
100
+ attribute? :community_chat_joined, CommunityChatJoined
99
101
  attribute? :community_chat_removed, CommunityChatRemoved
100
102
  attribute? :direct_message_price_changed, DirectMessagePriceChanged
101
103
  attribute? :forum_topic_created, ForumTopicCreated
@@ -110,6 +112,7 @@ module Telegram
110
112
  attribute? :giveaway_completed, GiveawayCompleted
111
113
  attribute? :managed_bot_created, ManagedBotCreated
112
114
  attribute? :paid_message_price_changed, PaidMessagePriceChanged
115
+ attribute? :paid_messages_waived, PaidMessagesWaived
113
116
  attribute? :poll_option_added, PollOptionAdded
114
117
  attribute? :poll_option_deleted, PollOptionDeleted
115
118
  attribute? :suggested_post_approved, SuggestedPostApproved
@@ -117,6 +120,7 @@ module Telegram
117
120
  attribute? :suggested_post_declined, SuggestedPostDeclined
118
121
  attribute? :suggested_post_paid, SuggestedPostPaid
119
122
  attribute? :suggested_post_refunded, SuggestedPostRefunded
123
+ attribute? :ton_wallet_transfer, TonWalletTransfer
120
124
  attribute? :video_chat_scheduled, VideoChatScheduled
121
125
  attribute? :video_chat_started, VideoChatStarted
122
126
  attribute? :video_chat_ended, VideoChatEnded
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class MessageGenerationStopped < Base
7
+ attribute :chat, Chat
8
+ attribute? :message_thread_id, Types::Integer
9
+ attribute :draft_id, Types::Integer
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,10 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class PaidMessagesWaived < Base
7
+ end
8
+ end
9
+ end
10
+ end
@@ -17,7 +17,7 @@ module Telegram
17
17
  attribute :members_only, Types::Bool
18
18
  attribute? :country_codes, Types::Array.of(Types::String)
19
19
  attribute? :correct_option_ids, Types::Array.of(Types::Integer)
20
- attribute? :explanation, Types::String
20
+ attribute? :explanation, Types::String.constrained(max_size: 200)
21
21
  attribute? :explanation_entities, Types::Array.of(MessageEntity)
22
22
  attribute? :explanation_media, PollMedia
23
23
  attribute? :open_period, Types::Integer
@@ -10,6 +10,7 @@ module Telegram
10
10
  attribute? :one_time_keyboard, Types::Bool.default(false)
11
11
  attribute? :input_field_placeholder, Types::String.constrained(min_size: 1, max_size: 64)
12
12
  attribute? :selective, Types::Bool
13
+ attribute? :force_reply, Types::Bool
13
14
 
14
15
  def to_compact_hash
15
16
  hsh = super
@@ -11,6 +11,7 @@ module Telegram
11
11
  attribute? :quote, Types::String
12
12
  attribute? :quote_parse_mode, Types::String
13
13
  attribute? :quote_entities, Types::Array.of(MessageEntity)
14
+ attribute? :quote_rich_texts, Types::Array.of(RichText).constrained(max_size: 32)
14
15
  attribute? :quote_position, Types::Integer
15
16
  attribute? :checklist_task_id, Types::Integer
16
17
  attribute? :poll_option_id, Types::String
@@ -15,14 +15,17 @@ module Telegram
15
15
  RichBlockAnchor |
16
16
  RichBlockList |
17
17
  RichBlockBlockQuotation |
18
+ RichBlockExpandableBlockQuotation |
18
19
  RichBlockPullQuotation |
19
20
  RichBlockCollage |
20
21
  RichBlockSlideshow |
21
22
  RichBlockTable |
22
23
  RichBlockDetails |
23
24
  RichBlockMap |
25
+ RichBlockButtons |
24
26
  RichBlockAnimation |
25
27
  RichBlockAudio |
28
+ RichBlockDocument |
26
29
  RichBlockPhoto |
27
30
  RichBlockVideo |
28
31
  RichBlockVoiceNote |
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class RichBlockButtons < Base
7
+ attribute :type, Types::String.constrained(eql: 'buttons').default('buttons')
8
+ attribute :buttons, Types::Array.of(RichMessageButton)
9
+ attribute? :align, Types::String
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class RichBlockDocument < Base
7
+ attribute :type, Types::String.constrained(eql: 'document').default('document')
8
+ attribute :document, Document
9
+ attribute? :caption, RichBlockCaption
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class RichBlockExpandableBlockQuotation < Base
7
+ attribute :type, Types::String.constrained(eql: 'expandable_blockquote').default('expandable_blockquote')
8
+ attribute :text, RichText
9
+ attribute? :credit, RichText
10
+ end
11
+ end
12
+ end
13
+ end
@@ -8,6 +8,7 @@ module Telegram
8
8
  attribute :cells, Types::Array.of(Types::Array.of(RichBlockTableCell))
9
9
  attribute? :is_bordered, Types::True
10
10
  attribute? :is_striped, Types::True
11
+ attribute? :is_compact, Types::True
11
12
  attribute? :caption, RichText
12
13
  end
13
14
  end
@@ -0,0 +1,21 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class RichMessageButton < Base
7
+ attribute :text, Types.deferred(:RichText)
8
+ attribute? :style, Types::String
9
+ attribute? :url, Types::String
10
+ attribute? :callback_data, Types::String
11
+ attribute? :web_app, WebAppInfo
12
+ attribute? :login_url, LoginUrl
13
+ attribute? :switch_inline_query, Types::String
14
+ attribute? :switch_inline_query_current_chat, Types::String
15
+ attribute? :switch_inline_query_chosen_chat, SwitchInlineQueryChosenChat
16
+ attribute? :copy_text, CopyTextButton
17
+ attribute? :disabled, DisabledButton
18
+ end
19
+ end
20
+ end
21
+ end
@@ -25,10 +25,12 @@ module Telegram
25
25
  RichTextEmailAddress |
26
26
  RichTextPhoneNumber |
27
27
  RichTextBankCardNumber |
28
+ RichTextTonAddress |
28
29
  RichTextMention |
29
30
  RichTextHashtag |
30
31
  RichTextCashtag |
31
32
  RichTextBotCommand |
33
+ RichTextButton |
32
34
  RichTextAnchor |
33
35
  RichTextAnchorLink |
34
36
  RichTextReference |
@@ -0,0 +1,12 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class RichTextButton < Base
7
+ attribute :type, Types::String.constrained(eql: 'button').default('button')
8
+ attribute :button, RichMessageButton
9
+ end
10
+ end
11
+ end
12
+ end
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class RichTextTonAddress < Base
7
+ attribute :type, Types::String.constrained(eql: 'ton_address').default('ton_address')
8
+ attribute :text, Types.deferred(:RichText)
9
+ attribute :address, Types::String
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class SharedWidgetQuery < Base
7
+ attribute :id, Types::String
8
+ attribute :from, User
9
+ attribute :type, WidgetQueryType
10
+ attribute :data, Types::String
11
+ attribute :widget_id, Types::String
12
+ end
13
+ end
14
+ end
15
+ end
@@ -4,7 +4,7 @@ module Telegram
4
4
  module Bot
5
5
  module Types
6
6
  class StoryArea < Base
7
- attribute :position, StoryAreaPosition
7
+ attribute :position, AreaPosition
8
8
  attribute :type, StoryAreaType
9
9
  end
10
10
  end
@@ -6,6 +6,7 @@ module Telegram
6
6
  class TextQuote < Base
7
7
  attribute :text, Types::String
8
8
  attribute? :entities, Types::Array.of(MessageEntity)
9
+ attribute? :rich_texts, Types::Array.of(RichText)
9
10
  attribute :position, Types::Integer
10
11
  attribute? :is_manual, Types::True
11
12
  end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class TonNft < Base
7
+ attribute :address, Types::String
8
+ attribute? :collection_address, Types::String
9
+ attribute :index, Types::String
10
+ attribute :name, Types::String
11
+ attribute :description, Types::String
12
+ attribute? :attributes, Types::Array.of(TonNftAttribute)
13
+ attribute? :gift, UniqueGift
14
+ end
15
+ end
16
+ end
17
+ end
@@ -0,0 +1,12 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class TonNftAttribute < Base
7
+ attribute :trait_type, Types::String
8
+ attribute :value, Types::String
9
+ end
10
+ end
11
+ end
12
+ end
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class TonWalletCard < Base
7
+ attribute :address, Types::String
8
+ attribute :amount, Types::String
9
+ attribute :stickers, Types::Array.of(TonWalletCardSticker)
10
+ attribute? :background_nft_address, Types::String
11
+ end
12
+ end
13
+ end
14
+ end
@@ -0,0 +1,12 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class TonWalletCardSticker < Base
7
+ attribute :position, AreaPosition
8
+ attribute :nft, TonNft
9
+ end
10
+ end
11
+ end
12
+ end
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class TonWalletTransfer < Base
7
+ attribute :transaction_id, Types::String
8
+ attribute :peer_address, Types::String
9
+ attribute :amount, Types::String
10
+ attribute? :comment, Types::String
11
+ end
12
+ end
13
+ end
14
+ end
@@ -6,6 +6,9 @@ module Telegram
6
6
  class UniqueGiftInfo < Base
7
7
  attribute :gift, UniqueGift
8
8
  attribute :origin, Types::String
9
+ attribute? :text, Types::String
10
+ attribute? :entities, Types::Array.of(MessageEntity)
11
+ attribute? :is_private, Types::True
9
12
  attribute? :last_resale_currency, Types::String
10
13
  attribute? :last_resale_amount, Types::Integer
11
14
  attribute? :owned_gift_id, Types::String
@@ -19,6 +19,8 @@ module Telegram
19
19
  attribute? :inline_query, InlineQuery
20
20
  attribute? :chosen_inline_result, ChosenInlineResult
21
21
  attribute? :callback_query, CallbackQuery
22
+ attribute? :widget_query, WidgetQuery
23
+ attribute? :shared_widget_query, SharedWidgetQuery
22
24
  attribute? :shipping_query, ShippingQuery
23
25
  attribute? :pre_checkout_query, PreCheckoutQuery
24
26
  attribute? :purchased_paid_media, PaidMediaPurchased
@@ -31,6 +33,7 @@ module Telegram
31
33
  attribute? :removed_chat_boost, ChatBoostRemoved
32
34
  attribute? :managed_bot, ManagedBotUpdated
33
35
  attribute? :subscription, BotSubscriptionUpdated
36
+ attribute? :stopped_message_generation, MessageGenerationStopped
34
37
 
35
38
  def current_message
36
39
  @current_message ||=
@@ -0,0 +1,16 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class Widget < Base
7
+ attribute? :id, Types::String
8
+ attribute? :width, Types::Integer
9
+ attribute? :height, Types::Integer
10
+ attribute :html, Types::String
11
+ attribute? :public_data, Types::String
12
+ attribute? :chat_data, Types::String
13
+ end
14
+ end
15
+ end
16
+ end
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class WidgetQuery < Base
7
+ attribute :id, Types::String
8
+ attribute :from, User
9
+ attribute? :chat, Chat
10
+ attribute? :message_id, Types::Integer
11
+ attribute? :inline_message_id, Types::String
12
+ attribute :chat_instance, Types::String
13
+ attribute? :chat_type, Types::String
14
+ attribute :type, WidgetQueryType
15
+ attribute :data, Types::String
16
+ attribute? :widget_id, Types::String
17
+ end
18
+ end
19
+ end
20
+ end
@@ -0,0 +1,16 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ ## Just for classes consistency
7
+ # rubocop:disable Naming/ConstantName
8
+ WidgetQueryType = (
9
+ WidgetQueryTypeData |
10
+ WidgetQueryTypeSignData |
11
+ WidgetQueryTypeSentTransaction
12
+ )
13
+ # rubocop:enable Naming/ConstantName
14
+ end
15
+ end
16
+ end
@@ -0,0 +1,12 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class WidgetQueryTypeData < Base
7
+ attribute :type, Types::String.constrained(eql: 'data').default('data')
8
+ attribute? :wallet_card, TonWalletCard
9
+ end
10
+ end
11
+ end
12
+ end
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class WidgetQueryTypeSentTransaction < Base
7
+ attribute :type, Types::String.constrained(eql: 'sent_transaction').default('sent_transaction')
8
+ attribute :wallet, WidgetQueryWallet
9
+ attribute :msg_hash, Types::String
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,13 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class WidgetQueryTypeSignData < Base
7
+ attribute :type, Types::String.constrained(eql: 'sign_data').default('sign_data')
8
+ attribute :wallet, WidgetQueryWallet
9
+ attribute :sign_data, Types::String
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Telegram
4
+ module Bot
5
+ module Types
6
+ class WidgetQueryWallet < Base
7
+ attribute :address, Types::String
8
+ attribute :amount, Types::String
9
+ attribute? :public_key, Types::String
10
+ attribute? :state_init, Types::String
11
+ end
12
+ end
13
+ end
14
+ end
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Telegram
4
4
  module Bot
5
- VERSION = '2.8.1'
5
+ VERSION = '2.9.0'
6
6
  end
7
7
  end
data/rakelib/README.md ADDED
@@ -0,0 +1,116 @@
1
+ # Bot API docs parser
2
+
3
+ The types in `lib/telegram/bot/types` and the endpoint list in `lib/telegram/bot/api/endpoints.rb` are generated from the [Telegram Bot API documentation](https://core.telegram.org/bots/api). This document explains how the documentation is turned into the data that the code is generated from.
4
+
5
+ To update the gem to a new Bot API version, follow the [Maintenance section](../README.md#maintenance) of the main README. Come back here if parsing fails.
6
+
7
+ ## Pipeline
8
+
9
+ ```mermaid
10
+ flowchart LR
11
+ web["core.telegram.org/bots/api"] -- "rake docs:fetch" --> html["data/bot_api.html"]
12
+ html -- "rake parse:types" --> types["data/types.json"]
13
+ html -- "rake parse:methods" --> methods["data/methods.json"]
14
+ types -- "rake rebuild:types" --> libtypes["lib/telegram/bot/types"]
15
+ methods -- "rake rebuild:methods" --> api["lib/telegram/bot/api/endpoints.rb"]
16
+ ```
17
+
18
+ - `docs:fetch` is the only step that uses the network. It saves the content of the page, without the site header and footer, to `data/bot_api.html`.
19
+ - `parse:*` reads only that snapshot, so parsing is reproducible and works offline.
20
+ - `rebuild:*` reads only the JSON files. It is implemented in `rakelib/builders` and is not covered here. The JSON format is the contract between the two halves.
21
+
22
+ The snapshot is committed. The parser specs read the same file, and one of them checks that parsing it produces exactly `data/types.json` and `data/methods.json`. If the snapshot, the parser, or the JSON files change without the others, the specs fail.
23
+
24
+ ## How the page is read
25
+
26
+ The page is a flat list of elements. Every type and every method is an `<h4>` heading followed by paragraphs and, usually, a table:
27
+
28
+ ```html
29
+ <h4>User</h4>
30
+ <p>This object represents a Telegram user or bot.</p>
31
+ <table>…</table>
32
+ <h4>Chat</h4>
33
+ <p>…</p>
34
+ <table>…</table>
35
+ ```
36
+
37
+ No element contains "the `User` type". The parser therefore walks the page once and cuts it into entries: a heading plus the blocks up to the next heading. Each entry is then identified by the first rule it matches in `DocsPage`:
38
+
39
+ ```ruby
40
+ GRAMMAR = EntryGrammar.new('h4') do
41
+ entry ApiMethod, named: /\A[a-z][A-Za-z0-9]*\z/
42
+ entry UnionType, named: TypeRef::NAME, with: 'ul'
43
+ entry ObjectType, named: TypeRef::NAME
44
+ skip named: /\s/
45
+ end
46
+ ```
47
+
48
+ Names carry most of the decision, because an entry made of paragraphs alone can be a method without parameters (`getMe`), an object without fields (`ForumTopicClosed`) or prose ("Sending files"). A heading that matches no rule raises.
49
+
50
+ From an entry down, the page is described with page objects: one class per thing on the page, each declaring the markup it expects. When the page changes, the class to fix is the one named after the thing that changed. The classes are in `rakelib/parsers`, one per file.
51
+
52
+ ```mermaid
53
+ flowchart TD
54
+ page["DocsPage"] -- "camelCase" --> method["ApiMethod"]
55
+ page -- "PascalCase, has a list" --> union["UnionType"]
56
+ page -- "PascalCase" --> object["ObjectType"]
57
+ object -- "table rows" --> field["Field"]
58
+ field -- "Type cell" --> typeref["TypeRef"]
59
+ field -- "Description cell" --> description["Description"]
60
+ method -- "paragraphs" --> returntype["ReturnType"]
61
+ method --> serializer["Serializer"]
62
+ union --> serializer
63
+ object --> serializer
64
+ serializer --> json["data/types.json, data/methods.json"]
65
+ ```
66
+
67
+ What the diagram does not show:
68
+
69
+ - An `ObjectType` without a table is valid: the object holds no information.
70
+ - A `UnionType` lists the types it can be one of, as `MessageOrigin` does.
71
+ - An `ApiMethod` has a name and a return type. Parameters are not parsed.
72
+ - `Description` and `ReturnType` read prose, because the documentation states constraints and return types only in sentences such as "Defaults to 25" or "Returns *True* on success". They are lists of patterns, and they are where a reworded page breaks the parser first.
73
+ - `Serializer` is the only class that knows the format of the JSON files.
74
+
75
+ ### Page objects
76
+
77
+ There are two kinds. An entry (`Entry`) is a heading and its blocks, and declares which blocks it reads by tag. Everything inside a block is real nested HTML, so the other page objects (`PageObject`) wrap one node and use CSS selectors or cell positions:
78
+
79
+ ```ruby
80
+ class ApiMethod < Entry
81
+ blocks :paragraphs, 'p'
82
+ block :table, 'table', as: Table
83
+ end
84
+
85
+ class Table < PageObject
86
+ texts :headers, 'th'
87
+ elements :rows, '> tbody > tr'
88
+ end
89
+
90
+ class Field < PageObject
91
+ cell :name, 0
92
+ cell :description, 2, as: Description
93
+ end
94
+ ```
95
+
96
+ The macros are defined in `entry.rb` and `page_object.rb`, and the mechanism behind the entry rules in `entry_grammar.rb`. Both kinds can define `validate!`, which runs when the object is created. An entry checks its shape there, down to the cells of its table, so a page whose entries can be listed has been read in full.
97
+
98
+ ## When the page changes
99
+
100
+ Wherever the page has structure, the parser checks it and raises `Parsers::Error` instead of guessing: the output becomes committed code, so a wrong guess would ship a wrong type. The message starts with the name of the type or method; find it in `data/bot_api.html` to see what changed.
101
+
102
+ | Message | Where to fix it |
103
+ | --- | --- |
104
+ | `cannot find the return type` | `return_type.rb`: the return sentence is worded in a new way. |
105
+ | `Unsupported type` | `type_ref.rb`: a type cell is not a name, an `Array of`, or an `or` of names. |
106
+ | `Unrecognised heading` | `docs_page.rb`: a heading fits none of the entry rules. |
107
+ | Anything else | `object_type.rb`, `union_type.rb`, `api_method.rb` or `field.rb`: the layout of an entry or a table changed. |
108
+
109
+ Two things are not checked and fail silently:
110
+
111
+ - A constraint that is worded in a new way is not recognised by `Description`, and the field is generated without it.
112
+ - A prose heading that is a single word would be read as a method or as an object without fields.
113
+
114
+ The way to catch both is to read the diff of the JSON files against the Bot API changelog.
115
+
116
+ A new kind of constraint, as opposed to a new wording of an existing one, also needs a new key in `Serializer` and support for it in `rakelib/builders`.
@@ -103,10 +103,9 @@ module Builders
103
103
  def apply_min_max!(attr_name, properties)
104
104
  return unless properties[:min_size] || properties[:max_size]
105
105
 
106
- constrain = '.constrained(minmax)'
107
- constrain = properties[:min_size] ? constrain.gsub('min', "min_size: #{properties[:min_size]}, ") : ''
108
- constrain = constrain.gsub('max', "max_size: #{properties[:max_size]}") if properties[:max_size]
109
- attributes[attr_name][:type] += constrain
106
+ bounds = properties.slice(:min_size, :max_size).compact
107
+ constraints = bounds.map { |key, value| "#{key}: #{value}" }.join(', ')
108
+ attributes[attr_name][:type] += ".constrained(#{constraints})"
110
109
  end
111
110
 
112
111
  def apply_default!(attr_name, properties, original_type)
data/rakelib/docs.rake ADDED
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'net/http'
4
+ require_relative 'parsers/docs_page'
5
+
6
+ namespace :docs do
7
+ desc 'Download the Telegram Bot API documentation to data/bot_api.html'
8
+ task :fetch do
9
+ response = Net::HTTP.get_response(URI(Parsers::DocsPage::URL))
10
+ raise "Failed to fetch #{Parsers::DocsPage::URL}: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
11
+
12
+ File.write Parsers::DocsPage::SNAPSHOT_PATH, Parsers::DocsPage.parse(response.body).to_html
13
+ puts 'Written to data/bot_api.html'
14
+ end
15
+ end