telegram_entities 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59bea042c497fc78acc233e6226d4e74fedd0350b98f5c04d532352531106f9f
+  data.tar.gz: f01c66585462f4f3e49f32739907a8777b9e2fbeefa056b95ce5c5f7ab20e086
+SHA512:
+  metadata.gz: 7fa8daab2f8252ce3792be80892beea8e6eab0c2af9ffcf0d5f8978fc0eb7c0d2af64344f2a943fcd56575ef1cf75ba706ca40e657117c3388a974fadc4d2389
+  data.tar.gz: 26a866427a665ae4198a0c863dbe6a96dd5db423d84a186bdfbe3708e5295cfa798b29d5ecb177719a0a7100a6bb0fa2f781adf0e1936e2e7de6439e5dd3dc6e

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-11-22
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Kirill Bobykin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,313 @@
+# TelegramEntities
+
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1.0-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)
+[![Gem Version](https://img.shields.io/gem/v/telegram_entities.svg)](https://rubygems.org/gems/telegram_entities)
+
+Ruby gem for converting Telegram message entities between HTML and Markdown formats. Supports all Telegram MessageEntity types with UTF-16 offset/length handling.
+
+📚 **Official Telegram Documentation:**
+- [MessageEntity Types](https://core.telegram.org/type/MessageEntity) - Complete schema of all entity types
+- [Styled Text with Message Entities](https://core.telegram.org/api/entities) - How Telegram styles text using entities
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add telegram_entities
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install telegram_entities
+```
+
+## Quick Start
+
+```ruby
+require 'telegram_entities'
+
+# Convert Markdown to Telegram entities
+entities = TelegramEntities.from_markdown('*bold* _italic_ `code`')
+puts entities.message
+# => "bold italic code"
+
+puts entities.entities
+# => [
+#   {"type"=>"bold", "offset"=>0, "length"=>4},
+#   {"type"=>"italic", "offset"=>5, "length"=>6},
+#   {"type"=>"code", "offset"=>12, "length"=>4}
+# ]
+```
+
+## Usage
+
+### Converting from Markdown to Entities
+
+Parse Markdown text and extract Telegram entities:
+
+```ruby
+require 'telegram_entities'
+
+text = '*Hello* _world_! Visit https://example.com'
+entities = TelegramEntities.from_markdown(text)
+
+puts entities.message
+# => "Hello world! Visit https://example.com"
+
+puts entities.entities.inspect
+# => [
+#   {"type"=>"bold", "offset"=>0, "length"=>5},
+#   {"type"=>"italic", "offset"=>6, "length"=>5},
+#   {"type"=>"url", "offset"=>18, "length"=>19}
+# ]
+```
+
+### Converting from HTML to Entities
+
+Parse HTML and extract Telegram entities:
+
+```ruby
+html = '<b>bold</b> <i>italic</i> <a href="https://example.com">link</a>'
+entities = TelegramEntities.from_html(html)
+
+puts entities.message
+# => "bold italic link"
+
+puts entities.entities
+# => [
+#   {"type"=>"bold", "offset"=>0, "length"=>4},
+#   {"type"=>"italic", "offset"=>5, "length"=>6},
+#   {"type"=>"text_url", "offset"=>12, "length"=>4, "url"=>"https://example.com"}
+# ]
+```
+
+### Converting from TDLib formattedText to Entities
+
+Convert TDLib formattedText (from [tdlib-ruby](https://github.com/southbridgeio/tdlib-ruby)) to TelegramEntities:
+
+```ruby
+require 'telegram_entities'
+
+# Get formattedText from TDLib
+puts tdlib_formatted_text.inspect
+# => #<TD::Types::FormattedText text="" entities=[]>
+
+# Convert to TelegramEntities
+entities = TelegramEntities.from_tdlib_formatted_text(tdlib_formatted_text.to_h)
+
+puts entities.message
+# => "text content"
+
+puts entities.entities
+# => [
+#   {"type"=>"bold", "offset"=>0, "length"=>4},
+#   {"type"=>"text_url", "offset"=>10, "length"=>5, "url"=>"https://example.com"}
+# ]
+```
+
+The method supports all TDLib text entity types and automatically converts them to TelegramEntities format.
+
+### Converting Entities to HTML
+
+Convert Telegram entities back to HTML:
+
+```ruby
+# Create entities manually
+entities = TelegramEntities.new('Hello world', [
+  {'type' => 'bold', 'offset' => 0, 'length' => 5},
+  {'type' => 'italic', 'offset' => 6, 'length' => 5}
+])
+
+html = entities.to_html
+puts html
+# => "<strong>Hello</strong> <em>world</em>"
+```
+
+### Telegram-Specific Tags
+
+When sending HTML to Telegram Bot API, use `allow_telegram_tags: true` to get Telegram-compatible tags. This is especially important for special entity types like spoilers, custom emojis, and cashtags:
+
+```ruby
+# Create entities with Telegram-specific types
+# Message: "$BTC 🚀 secret"
+entities = TelegramEntities.new('$BTC 🚀 secret', [
+  {'type' => 'cashtag', 'offset' => 0, 'length' => 4},      # $BTC
+  {'type' => 'custom_emoji', 'offset' => 5, 'length' => 2, 'custom_emoji_id' => 12345},  # 🚀
+  {'type' => 'spoiler', 'offset' => 7, 'length' => 6}      # secret
+])
+
+# Standard HTML (for web display)
+html_standard = entities.to_html
+puts html_standard
+# => "<span class=\"tg-cashtag\">$BTC</span> 🚀 <span class=\"tg-spoiler\">secret</span>"
+
+# Telegram-specific tags (for Telegram Bot API)
+html_telegram = entities.to_html(allow_telegram_tags: true)
+puts html_telegram
+# => "<tg-cashtag>$BTC</tg-cashtag> <tg-emoji emoji-id=\"12345\">🚀</tg-emoji> <tg-spoiler>secret</tg-spoiler>"
+```
+
+**Key differences for Telegram-specific entities:**
+
+| Entity Type | Standard HTML | Telegram Tags |
+|-------------|---------------|---------------|
+| **Spoiler** | `<span class="tg-spoiler">text</span>` | `<tg-spoiler>text</tg-spoiler>` |
+| **Custom Emoji** | `🚀` (plain text, no tags) | `<tg-emoji emoji-id="12345">🚀</tg-emoji>` |
+| **Cashtag** | `<span class="tg-cashtag">$BTC</span>` | `<tg-cashtag>$BTC</tg-cashtag>` |
+| **Hashtag** | `<span class="tg-hashtag">#tag</span>` | `<tg-hashtag>#tag</tg-hashtag>` |
+| **Bot Command** | `<span class="tg-bot-command">/start</span>` | `<tg-bot-command>/start</tg-bot-command>` |
+
+**When to use each mode:**
+- **Standard HTML** (`allow_telegram_tags: false`): For displaying in web browsers or general HTML rendering
+- **Telegram Tags** (`allow_telegram_tags: true`): For sending messages via Telegram Bot API using `parse_mode: 'HTML'`
+
+### Real-World Example
+
+```ruby
+require 'telegram_entities'
+
+# User sends a message with Markdown
+user_input = '*Important*: Check out https://github.com/qelphybox/telegram_entities_rb'
+
+# Convert to Telegram entities for Bot API
+entities = TelegramEntities.from_markdown(user_input)
+
+# Send to Telegram Bot API
+# bot.send_message(
+#   chat_id: chat_id,
+#   text: entities.message,
+#   entities: entities.entities
+# )
+
+# Later, convert received entities back to HTML for display
+html_entities = TelegramEntities.new(entities.message, entities.entities)
+html_output = html_entities.to_html
+# => "<strong>Important</strong>: Check out <a href=\"https://github.com/qelphybox/telegram_entities_rb\">https://github.com/qelphybox/telegram_entities_rb</a>"
+```
+
+## Supported Entity Types
+
+The gem supports **all** Telegram MessageEntity types. Here's a complete reference:
+
+> 📖 For the complete list of entity types and their specifications, see the [official Telegram documentation](https://core.telegram.org/type/MessageEntity).
+
+### 📝 Text Formatting
+
+| Type | Markdown | HTML | Description |
+|------|----------|------|-------------|
+| `bold` | `*text*` or `**text**` | `<b>text</b>` | Bold text |
+| `italic` | `_text_` or `*text*` | `<i>text</i>` | Italic text |
+| `underline` | `__text__` | `<u>text</u>` | Underlined text |
+| `strike` | `~~text~~` | `<s>text</s>` | Strikethrough text |
+| `code` | `` `code` `` | `<code>code</code>` | Inline code |
+| `pre` | ` ```code``` ` | `<pre>code</pre>` | Code block (with optional `language`) |
+| `spoiler` | `||text||` | `<tg-spoiler>text</tg-spoiler>` | Spoiler text |
+
+### 🔗 Links and References
+
+| Type | Example | HTML Output | Notes |
+|------|---------|-------------|-------|
+| `mention` | `@username` | `<a href="https://t.me/username">@username</a>` | Username mention |
+| `mention_name` | User by ID | `<a href="tg://user?id=123">Name</a>` | Requires `user.id` field |
+| `hashtag` | `#hashtag` | `#hashtag` | Hashtag |
+| `cashtag` | `$USD` | `$USD` | Cashtag |
+| `bot_command` | `/start` | `/start` | Bot command |
+| `url` | `https://example.com` | `<a href="https://example.com">https://example.com</a>` | Auto-detected URL |
+| `email` | `user@example.com` | `<a href="mailto:user@example.com">user@example.com</a>` | Auto-detected email |
+| `phone` | `+1234567890` | `<a href="tel:+1234567890">+1234567890</a>` | Auto-detected phone |
+| `text_url` | Custom link | `<a href="url">text</a>` | Requires `url` field |
+
+### 🎨 Media and Special
+
+| Type | Description | Required Fields |
+|------|-------------|----------------|
+| `custom_emoji` | Custom emoji | `custom_emoji_id` |
+| `media_timestamp` | Media timestamp | `media_timestamp` (integer) |
+| `bank_card` | Bank card number | - |
+
+### 💬 Block Quotes
+
+| Type | HTML | Description |
+|------|------|-------------|
+| `blockquote` | `<blockquote>text</blockquote>` | Block quote |
+| `expandable_blockquote` | `<blockquote expandable>text</blockquote>` | Expandable block quote |
+
+### Entity Structure
+
+Each entity is a hash with the following structure:
+
+```ruby
+{
+  'type' => 'bold',           # Entity type (required)
+  'offset' => 0,               # UTF-16 offset (required)
+  'length' => 4,               # UTF-16 length (required)
+  'url' => '...',             # For text_url type
+  'user' => {'id' => 123},    # For mention_name type
+  'custom_emoji_id' => 12345, # For custom_emoji type
+  'media_timestamp' => 30,    # For media_timestamp type
+  'language' => 'ruby'         # For pre type
+}
+```
+
+### Example with Complex Entities
+
+```ruby
+require 'telegram_entities'
+
+# Complex message with multiple entity types
+markdown = <<~TEXT
+  *Bold* and _italic_ text with `code`.
+  
+  Visit https://example.com or email user@example.com
+  
+  ||Spoiler text||
+TEXT
+
+entities = TelegramEntities.from_markdown(markdown)
+
+puts "Message: #{entities.message}"
+puts "\nEntities (#{entities.entities.length}):"
+entities.entities.each do |entity|
+  puts "  - #{entity['type']}: offset=#{entity['offset']}, length=#{entity['length']}"
+end
+```
+
+**Output:**
+```
+Message: Bold and italic text with code.
+
+Visit https://example.com or email user@example.com
+
+Spoiler text
+
+Entities (5):
+  - bold: offset=0, length=4
+  - italic: offset=9, length=6
+  - code: offset=22, length=4
+  - url: offset=35, length=19
+  - email: offset=59, length=19
+  - spoiler: offset=82, length=11
+```
+
+**⚠️ Important Note:** All offsets and lengths are in **UTF-16 code units**, not bytes or characters. The gem handles UTF-16 encoding automatically, so you don't need to worry about it!
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/qelphybox/telegram_entities_rb](https://github.com/qelphybox/telegram_entities_rb). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/qelphybox/telegram_entities_rb/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the TelegramEntities project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/qelphybox/telegram_entities_rb/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/telegram_entities/entities.rb

@@ -0,0 +1,462 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module TelegramEntities
+  # Class that represents a message + set of Telegram entities.
+  class Entities
+    attr_accessor :message, :entities
+
+    # Creates an Entities container using a message and a list of entities.
+    #
+    # @param message [String] Converted message
+    # @param entities [Array<Hash>] Converted entities
+    def initialize(message, entities = [])
+      @message = message
+      @entities = entities
+    end
+
+    # Manually convert markdown to a message and a set of entities.
+    #
+    # @param markdown [String] Markdown text
+    # @return [Entities] Object containing message and entities
+    def self.from_markdown(markdown)
+      markdown = markdown.tr("\r\n", "\n").strip
+      message = ""
+      message_len = 0
+      entities = []
+      offset = 0
+      stack = []
+
+      while offset < markdown.length
+        # Find next special character
+        special_chars = "*_~`[]|!\\"
+        len = 0
+        while offset + len < markdown.length && !special_chars.include?(markdown[offset + len])
+          len += 1
+        end
+
+        piece = markdown[offset, len]
+        offset += len
+
+        if offset >= markdown.length
+          message += piece
+          break
+        end
+
+        char = markdown[offset]
+        offset += 1
+        next_char = markdown[offset]
+
+        # Handle escape
+        if char == "\\"
+          message += piece + (next_char || "")
+          message_len += EntityTools.mb_strlen(piece) + 1
+          offset += 1 if next_char
+          next
+        end
+
+        # Handle double characters
+        if char == "_" && next_char == "_"
+          offset += 1
+          char = "__"
+        elsif char == "|"
+          if next_char == "|"
+            offset += 1
+            char = "||"
+          else
+            message += piece + char
+            message_len += EntityTools.mb_strlen(piece) + 1
+            next
+          end
+        elsif char == "!"
+          if next_char == "["
+            offset += 1
+            char = "]("
+          else
+            message += piece + char
+            message_len += EntityTools.mb_strlen(piece) + 1
+            next
+          end
+        elsif char == "["
+          char = "]("
+        elsif char == "]"
+          if stack.empty? || stack.last[0] != "]("
+            message += piece + char
+            message_len += EntityTools.mb_strlen(piece) + 1
+            next
+          end
+          if next_char != "("
+            stack.pop
+            message += "[" + piece + char
+            message_len += EntityTools.mb_strlen(piece) + 2
+            next
+          end
+          offset += 1
+          char = "]("
+        elsif char == "`"
+          message += piece
+          message_len += EntityTools.mb_strlen(piece)
+
+          token = "`"
+          language = nil
+          if next_char == "`" && markdown[offset + 1] == "`"
+            token = "```"
+            offset += 2
+            lang_len = 0
+            while offset + lang_len < markdown.length && !["\n", " "].include?(markdown[offset + lang_len])
+              lang_len += 1
+            end
+            language = markdown[offset, lang_len] if lang_len > 0
+            offset += lang_len
+            offset += 1 if markdown[offset] == "\n"
+          end
+
+          piece = ""
+          pos_close = offset
+          found = false
+          while pos_close < markdown.length
+            pos_close = markdown.index(token, pos_close)
+            unless pos_close
+              found = false
+              break
+            end
+
+            if pos_close > 0 && markdown[pos_close - 1] == "\\"
+              piece += markdown[offset, pos_close - offset - 1] + token
+              pos_close += token.length
+              offset = pos_close
+              next
+            end
+            found = true
+            break
+          end
+
+          raise "Unclosed #{token} opened @ pos #{offset}!" unless found
+
+          piece += markdown[offset, pos_close - offset]
+
+          start = message_len
+          message += piece
+          piece_len = EntityTools.mb_strlen(piece)
+          message_len += piece_len
+
+          # Trim trailing whitespace from piece
+          piece_bytes = piece.bytes
+          piece_len_bytes = piece_bytes.length
+          (piece_len_bytes - 1).downto(0) do |x|
+            char = piece_bytes[x]
+            break unless [32, 13, 10].include?(char) # space, \r, \n
+            piece_len -= 1
+          end
+
+          if piece_len > 0
+            entity = {
+              "type" => ((token == "```") ? "pre" : "code"),
+              "offset" => start,
+              "length" => piece_len
+            }
+            entity["language"] = language if language
+            entities << entity
+          end
+
+          offset = pos_close + token.length
+          next
+        end
+
+        # Handle closing tag
+        if !stack.empty? && stack.last[0] == char
+          _, start = stack.pop
+
+          if char == "]("
+            pos_close = offset
+            link = ""
+            while pos_close < markdown.length
+              pos_close = markdown.index(")", pos_close)
+              break unless pos_close
+
+              if pos_close > 0 && markdown[pos_close - 1] == "\\"
+                link += markdown[offset, pos_close - offset - 1]
+                offset = pos_close + 1
+                next
+              end
+              link += markdown[offset, pos_close - offset]
+              break
+            end
+
+            raise "Unclosed ) opened @ pos #{offset}!" unless pos_close
+
+            entity = handle_link(link)
+            offset = pos_close + 1
+          else
+            entity = case char
+            when "*" then {"type" => "bold"}
+            when "_" then {"type" => "italic"}
+            when "__" then {"type" => "underline"}
+            when "`" then {"type" => "code"}
+            when "~" then {"type" => "strike"}
+            when "||" then {"type" => "spoiler"}
+            else raise "Unknown char #{char} @ pos #{offset}!"
+            end
+          end
+
+          message += piece
+          message_len += EntityTools.mb_strlen(piece)
+
+          length_real = message_len - start
+          # Trim trailing whitespace from message
+          message_bytes = message.bytes
+          (message_bytes.length - 1).downto(0) do |x|
+            char = message_bytes[x]
+            break unless [32, 13, 10].include?(char) # space, \r, \n
+            length_real -= 1
+          end
+
+          if length_real > 0
+            entity["offset"] = start
+            entity["length"] = length_real
+            entities << entity
+          end
+        else
+          message += piece
+          message_len += EntityTools.mb_strlen(piece)
+          stack << [char, message_len]
+        end
+      end
+
+      raise "Found unclosed markdown elements #{stack.map(&:first).join(", ")}" unless stack.empty?
+
+      new(message.strip, entities)
+    end
+
+    # Manually convert HTML to a message and a set of entities.
+    #
+    # @param html [String] HTML text
+    # @return [Entities] Object containing message and entities
+    def self.from_html(html)
+      html = html.gsub(/<br(\s*)?\/?>/i, "\n")
+      # Use HTML parser to properly handle boolean attributes like 'expandable'
+      doc = Nokogiri::HTML::DocumentFragment.parse("<body>#{html.strip}</body>")
+      message = +""
+      entities = []
+      body = doc.at_css("body")
+      parse_node(body, 0, message, entities)
+      new(message.strip, entities)
+    end
+
+    # Convert a message and a set of entities to HTML.
+    #
+    # @param allow_telegram_tags [Boolean] Whether to allow telegram-specific tags
+    # @return [String] HTML string
+    def to_html(allow_telegram_tags = false)
+      insertions = {}
+      @entities.each do |entity|
+        offset = entity["offset"]
+        length = entity["length"]
+        insertions[offset] ||= ""
+
+        insertions[offset] += case entity["type"]
+        when "bold" then "<strong>"
+        when "italic" then "<i>"
+        when "code" then "<code>"
+        when "pre"
+          if entity["language"] && !entity["language"].empty?
+            "<pre language=\"#{EntityTools.html_escape(entity["language"])}\">"
+          else
+            "<pre>"
+          end
+        when "text_url" then "<a href=\"#{EntityTools.html_escape(entity["url"])}\">"
+        when "strike" then "<s>"
+        when "underline" then "<u>"
+        when "blockquote" then "<blockquote>"
+        when "url"
+          url = EntityTools.html_escape(EntityTools.mb_substr(@message, offset, length))
+          "<a href=\"#{url}\">"
+        when "email"
+          email = EntityTools.html_escape(EntityTools.mb_substr(@message, offset, length))
+          "<a href=\"mailto:#{email}\">"
+        when "phone"
+          phone = EntityTools.html_escape(EntityTools.mb_substr(@message, offset, length))
+          "<a href=\"phone:#{phone}\">"
+        when "mention"
+          mention = EntityTools.html_escape(EntityTools.mb_substr(@message, offset + 1, length - 1))
+          "<a href=\"https://t.me/#{mention}\">"
+        when "spoiler"
+          allow_telegram_tags ? "<tg-spoiler>" : '<span class="tg-spoiler">'
+        when "custom_emoji"
+          allow_telegram_tags ? "<tg-emoji emoji-id=\"#{entity["custom_emoji_id"]}\">" : ""
+        when "mention_name"
+          allow_telegram_tags ? "<a href=\"tg://user?id=#{entity["user"]["id"]}\">" : ""
+        when "hashtag"
+          allow_telegram_tags ? "<tg-hashtag>" : '<span class="tg-hashtag">'
+        when "cashtag"
+          allow_telegram_tags ? "<tg-cashtag>" : '<span class="tg-cashtag">'
+        when "bot_command"
+          allow_telegram_tags ? "<tg-bot-command>" : '<span class="tg-bot-command">'
+        when "media_timestamp"
+          media_timestamp = entity["media_timestamp"]
+          if allow_telegram_tags && media_timestamp
+            "<tg-media-timestamp timestamp=\"#{EntityTools.html_escape(media_timestamp.to_s)}\">"
+          else
+            '<span class="tg-media-timestamp">'
+          end
+        when "bank_card"
+          allow_telegram_tags ? "<tg-bank-card-number>" : '<span class="tg-bank-card-number">'
+        when "expandable_blockquote"
+          allow_telegram_tags ? "<blockquote expandable>" : '<blockquote class="expandable">'
+        else ""
+        end
+
+        end_offset = offset + length
+        insertions[end_offset] ||= ""
+        insertions[end_offset] = case entity["type"]
+        when "bold" then "</strong>"
+        when "italic" then "</i>"
+        when "code" then "</code>"
+        when "pre" then "</pre>"
+        when "text_url", "url", "email", "mention", "phone" then "</a>"
+        when "strike" then "</s>"
+        when "underline" then "</u>"
+        when "blockquote" then "</blockquote>"
+        when "spoiler" then allow_telegram_tags ? "</tg-spoiler>" : "</span>"
+        when "custom_emoji" then allow_telegram_tags ? "</tg-emoji>" : ""
+        when "mention_name" then allow_telegram_tags ? "</a>" : ""
+        when "hashtag" then allow_telegram_tags ? "</tg-hashtag>" : "</span>"
+        when "cashtag" then allow_telegram_tags ? "</tg-cashtag>" : "</span>"
+        when "bot_command" then allow_telegram_tags ? "</tg-bot-command>" : "</span>"
+        when "media_timestamp" then allow_telegram_tags ? "</tg-media-timestamp>" : "</span>"
+        when "bank_card" then allow_telegram_tags ? "</tg-bank-card-number>" : "</span>"
+        when "expandable_blockquote" then "</blockquote>"
+        else ""
+        end + insertions[end_offset]
+      end
+
+      insertions = insertions.sort.to_h
+      final = ""
+      pos = 0
+      insertions.each do |ins_offset, insertion|
+        final += EntityTools.html_escape(EntityTools.mb_substr(@message, pos, ins_offset - pos))
+        final += insertion
+        pos = ins_offset
+      end
+      final += EntityTools.html_escape(EntityTools.mb_substr(@message, pos))
+      final.gsub("\n", "<br>")
+    end
+
+    # Parse HTML node recursively
+    def self.parse_node(node, offset, message, entities)
+      if node.text?
+        text = node.text
+        message << text
+        return EntityTools.mb_strlen(text)
+      end
+
+      if node.name == "br"
+        message << "\n"
+        return 1
+      end
+
+      entity = case node.name
+      when "s", "strike", "del" then {"type" => "strike"}
+      when "u" then {"type" => "underline"}
+      when "b", "strong" then {"type" => "bold"}
+      when "i", "em" then {"type" => "italic"}
+      when "code" then {"type" => "code"}
+      when "spoiler", "tg-spoiler" then {"type" => "spoiler"}
+      when "pre"
+        if node["language"]
+          {"type" => "pre", "language" => node["language"]}
+        else
+          {"type" => "pre"}
+        end
+      when "span"
+        case node["class"]
+        when "tg-spoiler"
+          {"type" => "spoiler"}
+        when "tg-hashtag"
+          {"type" => "hashtag"}
+        when "tg-cashtag"
+          {"type" => "cashtag"}
+        when "tg-bot-command"
+          {"type" => "bot_command"}
+        when "tg-media-timestamp"
+          media_timestamp = node["timestamp"] || node["data-timestamp"]
+          if media_timestamp
+            {"type" => "media_timestamp", "media_timestamp" => media_timestamp.to_i}
+          else
+            {"type" => "media_timestamp"}
+          end
+        when "tg-bank-card-number"
+          {"type" => "bank_card"}
+        end
+      when "tg-emoji"
+        {"type" => "custom_emoji", "custom_emoji_id" => node["emoji-id"].to_i}
+      when "emoji"
+        {"type" => "custom_emoji", "custom_emoji_id" => node["id"].to_i}
+      when "tg-hashtag"
+        {"type" => "hashtag"}
+      when "tg-cashtag"
+        {"type" => "cashtag"}
+      when "tg-bot-command"
+        {"type" => "bot_command"}
+      when "tg-media-timestamp"
+        media_timestamp = node["timestamp"] || node["data-timestamp"]
+        if media_timestamp
+          {"type" => "media_timestamp", "media_timestamp" => media_timestamp.to_i}
+        else
+          {"type" => "media_timestamp"}
+        end
+      when "tg-bank-card-number"
+        {"type" => "bank_card"}
+      when "blockquote"
+        # Check for expandable attribute or class
+        if !node["expandable"].nil? || node["class"] == "expandable"
+          {"type" => "expandable_blockquote"}
+        else
+          {"type" => "blockquote"}
+        end
+      when "a"
+        handle_link(node["href"] || "")
+      end
+
+      length = 0
+      node.children.each do |child|
+        length += parse_node(child, offset + length, message, entities)
+      end
+
+      if entity
+        length_real = length
+        # Trim trailing whitespace from message
+        message_bytes = message.bytes
+        (message_bytes.length - 1).downto(0) do |x|
+          char = message_bytes[x]
+          break unless [32, 13, 10].include?(char) # space, \r, \n
+          length_real -= 1
+        end
+
+        if length_real > 0
+          entity["offset"] = offset
+          entity["length"] = length_real
+          entities << entity
+        end
+      end
+
+      length
+    end
+
+    # Handle link href
+    def self.handle_link(href)
+      if (match = href.match(/^mention:(.+)/)) || (match = href.match(/^tg:\/\/user\?id=(.+)/))
+        user_id = match[1].to_i
+        {"type" => "mention_name", "user" => {"id" => user_id}}
+      elsif (match = href.match(/^emoji:(\d+)$/)) || (match = href.match(/^tg:\/\/emoji\?id=(.+)/))
+        emoji_id = match[1].to_i
+        {"type" => "custom_emoji", "custom_emoji_id" => emoji_id}
+      else
+        {"type" => "text_url", "url" => href}
+      end
+    end
+
+    private_class_method :parse_node, :handle_link
+  end
+end

data/lib/telegram_entities/entity_tools.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module TelegramEntities
+  # Telegram UTF-16 styled text entity tools.
+  module EntityTools
+    # Get length of string in UTF-16 code points.
+    #
+    # @param text [String] Text
+    # @return [Integer] Length in UTF-16 code units
+    def self.mb_strlen(text)
+      # Convert to UTF-16 and count code units
+      # Each character in UTF-16 is 2 bytes, but surrogate pairs (for emojis) take 4 bytes (2 code units)
+      utf16 = text.encode("UTF-16BE")
+      utf16.bytesize / 2
+    end
+
+    # Telegram UTF-16 multibyte substring.
+    #
+    # @param text [String] Text to substring
+    # @param offset [Integer] Offset in UTF-16 code units
+    # @param length [Integer, nil] Length in UTF-16 code units
+    # @return [String] Substring
+    def self.mb_substr(text, offset, length = nil)
+      utf16 = text.encode("UTF-16BE")
+      byte_offset = offset * 2
+      byte_length = length ? length * 2 : nil
+      substring = if byte_length
+        utf16.byteslice(byte_offset, byte_length)
+      else
+        utf16.byteslice(byte_offset..-1)
+      end
+      substring&.force_encoding("UTF-16BE")&.encode("UTF-8") || ""
+    end
+
+    # Telegram UTF-16 multibyte split.
+    #
+    # @param text [String] Text
+    # @param length [Integer] Length in UTF-16 code units
+    # @return [Array<String>] Array of strings
+    def self.mb_str_split(text, length)
+      utf16 = text.encode("UTF-16BE")
+      byte_length = length * 2
+      result = []
+      offset = 0
+      while offset < utf16.bytesize
+        chunk = utf16.byteslice(offset, byte_length)
+        break if chunk.nil?
+        chunk.force_encoding("UTF-16BE")
+        result << chunk.encode("UTF-8")
+        offset += byte_length
+      end
+      result
+    end
+
+    # Telegram UTF-16 multibyte subreplace.
+    #
+    # @param string [String] Text
+    # @param replace [String] Replacement
+    # @param offset [Integer] Offset in UTF-16 code units
+    # @param length [Integer, nil] Length in UTF-16 code units
+    # @return [String] Result string
+    def self.mb_substr_replace(string, replace, offset, length = nil)
+      utf16_string = string.encode("UTF-16BE")
+      utf16_replace = replace.encode("UTF-16BE")
+      byte_offset = offset * 2
+      byte_length = length ? length * 2 : nil
+
+      result = if byte_length
+        utf16_string.byteslice(0, byte_offset) +
+          utf16_replace +
+          utf16_string.byteslice(byte_offset + byte_length..-1)
+      else
+        utf16_string.byteslice(0, byte_offset) + utf16_replace
+      end
+
+      result.force_encoding("UTF-16BE").encode("UTF-8")
+    end
+
+    # Escape string for this library's HTML entity converter.
+    #
+    # @param what [String] String to escape
+    # @return [String] Escaped string
+    def self.html_escape(what)
+      CGI.escapeHTML(what)
+    end
+
+    # Escape string for markdown.
+    #
+    # @param what [String] String to escape
+    # @return [String] Escaped string
+    def self.markdown_escape(what)
+      what.gsub(/[\\_*\[\]()~`>#+\-=|{}.!]/) { |char| "\\#{char}" }
+    end
+
+    # Escape string for markdown codeblock.
+    #
+    # @param what [String] String to escape
+    # @return [String] Escaped string
+    def self.markdown_codeblock_escape(what)
+      what.gsub("```") { "\\```" }
+    end
+
+    # Escape string for markdown code section.
+    #
+    # @param what [String] String to escape
+    # @return [String] Escaped string
+    def self.markdown_code_escape(what)
+      what.gsub("`") { "\\`" }
+    end
+
+    # Escape string for URL.
+    #
+    # @param what [String] String to escape
+    # @return [String] Escaped string
+    def self.markdown_url_escape(what)
+      what.gsub(")", '\\)')
+    end
+  end
+end

data/lib/telegram_entities/tdlib_converter.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module TelegramEntities
+  # Converter for TDLib formattedText to TelegramEntities format
+  module TdlibConverter
+    # Mapping from TDLib entity types to TelegramEntities types
+    TYPE_MAPPING = {
+      "textEntityTypeMention" => "mention",
+      "textEntityTypeHashtag" => "hashtag",
+      "textEntityTypeCashtag" => "cashtag",
+      "textEntityTypeBotCommand" => "bot_command",
+      "textEntityTypeUrl" => "url",
+      "textEntityTypeEmailAddress" => "email",
+      "textEntityTypePhoneNumber" => "phone",
+      "textEntityTypeBankCardNumber" => "bank_card",
+      "textEntityTypeBold" => "bold",
+      "textEntityTypeItalic" => "italic",
+      "textEntityTypeUnderline" => "underline",
+      "textEntityTypeStrikethrough" => "strike",
+      "textEntityTypeSpoiler" => "spoiler",
+      "textEntityTypeCode" => "code",
+      "textEntityTypePre" => "pre",
+      "textEntityTypePreCode" => "pre",
+      "textEntityTypeBlockQuote" => "blockquote",
+      "textEntityTypeExpandableBlockQuote" => "expandable_blockquote",
+      "textEntityTypeTextUrl" => "text_url",
+      "textEntityTypeMentionName" => "mention_name",
+      "textEntityTypeCustomEmoji" => "custom_emoji",
+      "textEntityTypeMediaTimestamp" => "media_timestamp"
+    }.freeze
+
+    # Convert TDLib formattedText data to TelegramEntities format
+    #
+    # @param data [Hash] TDLib formattedText data with keys: "text", "@type", "entities"
+    # @return [Array<String, Array<Hash>>] Array containing text and converted entities
+    def self.convert_tdlib_data(data)
+      text = data["text"] || ""
+      tdlib_entities = data["entities"] || []
+
+      converted_entities = tdlib_entities.map do |entity|
+        convert_entity(entity)
+      end.compact
+
+      [text, converted_entities]
+    end
+
+    # Convert a single TDLib entity to TelegramEntities format
+    #
+    # @param entity [Hash] TDLib entity with keys: "type", "offset", "length"
+    # @return [Hash, nil] Converted entity or nil if type is not supported
+    def self.convert_entity(entity)
+      entity_type = entity["type"]
+      return nil unless entity_type.is_a?(Hash)
+
+      tdlib_type = entity_type["@type"]
+      telegram_type = TYPE_MAPPING[tdlib_type]
+      return nil unless telegram_type
+
+      converted = {
+        "type" => telegram_type,
+        "offset" => entity["offset"] || 0,
+        "length" => entity["length"] || 0
+      }
+
+      # Handle special fields based on entity type
+      case tdlib_type
+      when "textEntityTypeTextUrl"
+        converted["url"] = entity_type["url"] if entity_type["url"]
+      when "textEntityTypeMentionName"
+        if entity_type["user_id"]
+          converted["user"] = {"id" => entity_type["user_id"]}
+        end
+      when "textEntityTypeCustomEmoji"
+        converted["custom_emoji_id"] = entity_type["custom_emoji_id"] if entity_type["custom_emoji_id"]
+      when "textEntityTypePreCode"
+        converted["language"] = entity_type["language"] if entity_type["language"]
+      when "textEntityTypePre"
+        converted["language"] = entity_type["language"] if entity_type["language"]
+      when "textEntityTypeMediaTimestamp"
+        converted["media_timestamp"] = entity_type["media_timestamp"] if entity_type["media_timestamp"]
+      end
+
+      converted
+    end
+
+    private_class_method :convert_entity
+  end
+end

data/lib/telegram_entities/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TelegramEntities
+  VERSION = "0.1.0"
+end

data/lib/telegram_entities.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "telegram_entities/version"
+require_relative "telegram_entities/entity_tools"
+require_relative "telegram_entities/entities"
+require_relative "telegram_entities/tdlib_converter"
+
+module TelegramEntities
+  class Error < StandardError; end
+
+  # Alias for TelegramEntities::Entities
+  def self.new(*args, **kwargs)
+    Entities.new(*args, **kwargs)
+  end
+
+  # Delegate class methods to Entities
+  def self.from_markdown(*args, **kwargs)
+    Entities.from_markdown(*args, **kwargs)
+  end
+
+  def self.from_html(*args, **kwargs)
+    Entities.from_html(*args, **kwargs)
+  end
+
+  # Convert TDLib formattedText to TelegramEntities
+  #
+  # @param data [Hash] TDLib formattedText data with keys: "text", "@type", "entities"
+  # @return [Entities] Object containing message and entities
+  def self.from_tdlib_formatted_text(data)
+    text, entities = TdlibConverter.convert_tdlib_data(data)
+    Entities.new(text, entities)
+  end
+end

data/sig/telegram_entities.rbs

@@ -0,0 +1,4 @@
+module TelegramEntities
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: telegram_entities
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kirill Bobykin
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Ruby gem for converting Telegram message entities between HTML and Markdown
+  formats. Supports all Telegram MessageEntity types with UTF-16 offset/length handling.
+email:
+- qelphybox@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/telegram_entities.rb
+- lib/telegram_entities/entities.rb
+- lib/telegram_entities/entity_tools.rb
+- lib/telegram_entities/tdlib_converter.rb
+- lib/telegram_entities/version.rb
+- sig/telegram_entities.rbs
+homepage: https://github.com/qelphybox/telegram_entities_rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/qelphybox/telegram_entities_rb
+  source_code_uri: https://github.com/qelphybox/telegram_entities_rb
+  changelog_uri: https://github.com/qelphybox/telegram_entities_rb/blob/master/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby gem for converting Telegram message entities between HTML and Markdown
+  formats
+test_files: []