grammerb 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e0a2199adf7c1a5140d3b584391bd015d2a900af94e0f4e363a83ceaa28703a
+  data.tar.gz: 67dd66363f2f48aabea7c8455d54c4ab0fe7b191b81342c70d04ec81036d5f96
+SHA512:
+  metadata.gz: 20afead47786b1a6f0c780d79d6e2a36c2303efccb15e5ebeeaf9516fd94664b5d0a94d2adfe1e4d66f75f6770c52ca6c6955d5165956e5db34f8ce36b2bbc02
+  data.tar.gz: 5ec252049f8f9a360720266b4438b53997e1e034a501a57a9b1266d967978df924b097c557447c59457078ced114adae3c6680b2640767baddc1e902ccd10833

data/README.md

@@ -0,0 +1,554 @@
+# Grammerb
+
+Grammerb -- as in (Tele)**gramme.rb** -- is a Telegram MTProto client library for Ruby. It wraps the Rust [grammers](https://github.com/Lonami/grammers) crate via native extensions, giving you a direct MTProto connection instead of going through the Bot HTTP API.
+
+It works for both user accounts and bots.
+
+## Requirements
+
+- Ruby >= 3.1
+- Rust toolchain (for compiling the native extension)
+- `libclang-dev` and `ruby-dev` system packages
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "grammerb", path: "/path/to/grammerb"
+```
+
+Then build the native extension:
+
+```bash
+bundle install
+rake compile
+```
+
+## Quick start
+
+### Bot login
+
+```ruby
+require "grammerb"
+
+client = Grammerb::Client.new(
+  api_id: ENV["API_ID"].to_i,
+  api_hash: ENV["API_HASH"],
+  session: "bot.session"
+)
+client.bot_start(token: ENV["BOT_TOKEN"])
+
+client.on(Grammerb::Events::NewMessage, pattern: /^\/start/) do |event|
+  event.reply("Hello!")
+end
+
+client.run
+```
+
+### User login
+
+```ruby
+client = Grammerb::Client.new(
+  api_id: ENV["API_ID"].to_i,
+  api_hash: ENV["API_HASH"],
+  session: "user.session"
+)
+client.start(phone: "+1234567890")
+```
+
+You can pass callbacks instead of reading from stdin:
+
+```ruby
+client.start(
+  phone: "+1234567890",
+  code_callback: -> { get_code_from_somewhere },
+  password_callback: -> { get_2fa_password }
+)
+```
+
+The session file is saved after authentication, so you only need to log in once.
+
+## Client options
+
+```ruby
+client = Grammerb::Client.new(
+  api_id: 12345,
+  api_hash: "abc123",
+  session: "grammerb.session",  # session file path (default: "grammerb.session")
+  proxy: "socks5://host:port",  # SOCKS5 proxy (optional)
+  logger: Logger.new($stdout),  # custom logger (optional, defaults to stderr at WARN level)
+  pool_size: 20                 # handler thread pool size (default: 20)
+)
+```
+
+## API
+
+### Connection
+
+```ruby
+client.connect
+client.disconnect
+client.authorized?
+client.save_session
+client.sign_out
+```
+
+### Messages
+
+```ruby
+# Send with all options
+client.send_message(chat, "text",
+  reply_to: msg_id,
+  parse_mode: "html",       # "html" or "markdown"
+  silent: true,              # no notification
+  link_preview: false,       # disable link preview
+  schedule: Time.now + 3600, # scheduled message (unix timestamp)
+  buttons: buttons           # inline keyboard (see below)
+)
+
+client.edit_message(chat, message_id, "new text", parse_mode: "html", buttons: buttons)
+client.delete_messages(chat, msg_id1, msg_id2, msg_id3)
+client.forward_messages(from_chat, [msg_id], to_chat)
+client.get_messages(chat, limit: 20)
+client.get_messages_by_id(chat, 123, 456)
+client.search_messages(chat, query: "keyword", limit: 100)
+client.search_all_messages(query: "keyword", limit: 100)
+client.pin_message(chat, message_id)
+client.unpin_message(chat, message_id)
+client.unpin_all_messages(chat)
+client.get_pinned_message(chat)
+client.get_reply_to_message(chat, message_id)
+client.send_reactions(chat, message_id, "thumbs_up")
+client.send_chat_action(chat, "typing")
+```
+
+### Inline keyboards
+
+```ruby
+buttons = [
+  [
+    { text: "Click me", callback_data: "btn1" },
+    { text: "Open link", url: "https://example.com" },
+    { text: "Switch inline", switch_inline: "query" }
+  ]
+]
+client.send_message(chat, "Pick one:", buttons: buttons)
+client.edit_message(chat, msg_id, "Updated", buttons: buttons)
+client.send_file(chat, "/path/to/file.pdf", caption: "Doc", buttons: buttons)
+```
+
+### Reply keyboards
+
+```ruby
+keys = [
+  ["Option A", "Option B"],
+  [{ text: "Share Phone", request_phone: true }]
+]
+client.send_reply_keyboard(chat, "Choose:", keys,
+  resize: true,
+  single_use: false,
+  placeholder: "Pick an option..."
+)
+client.remove_keyboard(chat)
+client.remove_keyboard(chat, "Custom removal text")
+client.force_reply(chat, "What is your name?")
+```
+
+### Files and media
+
+```ruby
+client.send_file(chat, "/path/to/file.pdf", caption: "Document", parse_mode: "html")
+client.send_photo(chat, "/path/to/image.jpg", caption: "Photo", parse_mode: "html")
+client.send_video(chat, "/path/to/video.mp4",
+  caption: "Video", parse_mode: "html",
+  duration: 30, width: 1920, height: 1080, supports_streaming: true
+)
+client.send_audio(chat, "/path/to/song.mp3",
+  caption: "Song", parse_mode: "html",
+  duration: 180, title: "Song Title", performer: "Artist"
+)
+client.send_voice(chat, "/path/to/voice.ogg", caption: "Voice", duration: 5)
+
+# Albums (grouped media)
+client.send_album(chat, "/path/a.jpg", "/path/b.jpg")
+client.send_album(chat, { path: "/a.jpg" }, { path: "/b.jpg" })
+
+# Download
+client.download_media(chat, message_id, "/path/to/save")
+
+# Download with progress
+client.download_media(chat, message_id, "/path/to/save") do |downloaded, total|
+  puts "#{downloaded}/#{total} bytes"
+end
+
+# Upload management
+idx = client.upload_file("/path/to/file")
+client.clear_uploaded(idx)
+client.clear_all_uploads
+```
+
+### Polls
+
+```ruby
+client.send_poll(chat, "Favorite color?", ["Red", "Blue", "Green"])
+client.send_poll(chat, "Capital of France?", ["London", "Paris", "Berlin"], quiz: true, correct_option: 1)
+client.get_poll_results(chat, message_id)
+client.get_poll_votes(chat, message_id, option: 0, limit: 100)
+```
+
+### Dialogs
+
+```ruby
+dialogs = client.iter_dialogs(limit: 100)  # alias: get_dialogs
+dialogs.each do |d|
+  puts "#{d.name} (#{d.peer_type}) - #{d.unread_count} unread"
+  puts "  Last: #{d.last_message_text}"
+end
+client.delete_dialog(chat)
+client.mark_as_read(chat)
+client.clear_mentions(chat)
+```
+
+### Users and chats
+
+```ruby
+me = client.get_me        # => Types::User
+me.id, me.first_name, me.last_name, me.username, me.phone, me.bot?
+
+peer = client.resolve_username("durov")  # => Types::Peer
+peer.id, peer.name, peer.peer_type
+
+results = client.search_peer("query", limit: 10)
+
+participants = client.iter_participants(chat, limit: 200)  # alias: get_participants
+participants.each { |p| puts "#{p.full_name} (@#{p.username})" }
+
+client.kick_participant(chat, user_id)
+client.set_admin_rights(chat, user_id, post_messages: true)
+client.set_banned_rights(chat, user_id, send_messages: true)
+
+perms = client.get_permissions(chat, user_id)
+perms.admin?, perms.creator?, perms.banned?, perms.has_default_permissions
+
+client.join_chat("https://t.me/+invite_link")
+link = client.export_invite_link(chat)
+client.block_user(user_id)
+client.unblock_user(user_id)
+client.iter_profile_photos(peer_id, limit: 10)
+```
+
+### Bots
+
+```ruby
+client.inline_query("@bot", "search term", limit: 20)
+client.answer_callback_query(query_id, text: "Done!", alert: false, cache_time: 60)
+client.answer_inline_query(query_id, results,
+  cache_time: 300,
+  is_personal: false,
+  next_offset: "page2"
+)
+```
+
+### Sessions
+
+```ruby
+encoded = client.export_session
+Grammerb::Client.import_session(encoded, path: "copy.session")
+```
+
+### Raw TL
+
+```ruby
+response_bytes = client.invoke_raw(request_bytes)
+```
+
+## Events
+
+Register handlers with `client.on` and call `client.run` to start the event loop.
+
+```ruby
+# All new messages
+client.on(Grammerb::Events::NewMessage) { |e| puts e.text }
+
+# Pattern matching
+client.on(Grammerb::Events::NewMessage, pattern: /^\/help/) { |e| e.reply("Help text") }
+
+# Filter by chat
+client.on(Grammerb::Events::NewMessage, chats: ["mychannel", -100123456]) { |e| ... }
+
+# Callback queries (inline button presses)
+client.on(Grammerb::Events::CallbackQuery) do |e|
+  e.answer(text: "Button pressed", alert: true, cache_time: 60)
+  puts e.data_str       # callback_data as UTF-8 string
+  puts e.chat_id
+  puts e.sender_id
+  puts e.message_id
+end
+
+# Message edits
+client.on(Grammerb::Events::MessageEdited) { |e| puts "Edited: #{e.text}" }
+
+# Message deletions
+client.on(Grammerb::Events::MessageDeleted) do |e|
+  puts "Deleted: #{e.deleted_ids}"
+  puts "In chat: #{e.chat_id}"
+end
+
+# Inline queries
+client.on(Grammerb::Events::InlineQuery) do |e|
+  puts e.query, e.offset, e.sender_id
+  e.answer(results, cache_time: 300, is_personal: false, next_offset: "2")
+end
+
+# Inline send (when user picks an inline result)
+client.on(Grammerb::Events::InlineSend) { |e| puts e.sender_id }
+
+# Albums (grouped media) -- automatically buffered from individual messages
+client.on(Grammerb::Events::Album) do |e|
+  puts "Album with #{e.messages.size} items in #{e.chat_name}"
+  puts e.texts
+  e.reply("Nice album!")
+end
+
+# Raw/unhandled updates
+client.on(Grammerb::Events::RawUpdate) { |e| puts e.raw }
+
+# Update errors
+client.on(Grammerb::Events::UpdateError) { |e| puts e.message }
+
+# Remove a handler
+handler = client.on(Grammerb::Events::NewMessage) { |e| ... }
+client.off(handler)
+
+# Stop the event loop
+client.stop
+```
+
+### Alternative event loop
+
+Instead of handler registration, you can iterate updates directly:
+
+```ruby
+client.each_update do |event|
+  case event
+  when Grammerb::Events::NewMessage
+    puts event.text
+  when Grammerb::Events::CallbackQuery
+    event.answer(text: "ok")
+  end
+end
+```
+
+### Event fields
+
+NewMessage and MessageEdited events share these fields:
+
+```ruby
+event.message_id
+event.text
+event.chat_id
+event.chat_name
+event.sender_id
+event.sender_name
+event.date          # Time object
+event.chat_type     # "user", "chat", or "channel"
+event.grouped_id    # non-nil for album messages
+event.sender_is_bot
+event.private?      # chat_type == "user"
+event.group?        # chat_type == "chat"
+event.channel?      # chat_type == "channel"
+event.bot?          # sender is a bot
+event.album?        # part of a grouped album
+event.reply("text")
+event.edit("new text", parse_mode: "html")
+event.delete
+event.forward(other_chat)
+```
+
+## Types
+
+### Message
+
+Returned by `get_messages`, `get_messages_by_id`, `search_messages`, etc.
+
+```ruby
+msg.id
+msg.text
+msg.chat_id
+msg.chat_name
+msg.sender_id
+msg.sender_name
+msg.date                  # Time object
+msg.chat_type             # "user", "chat", "channel"
+msg.grouped_id
+msg.reply_to_message_id
+
+# Media
+msg.has_media?
+msg.media_type            # "photo", "document", "sticker", "poll", "contact",
+                          # "geo", "venue", "dice", "geo_live", "web_page"
+msg.photo?
+msg.document?
+msg.sticker?
+msg.poll?
+msg.album?
+msg.media_id
+msg.media_file_name
+msg.media_mime_type
+msg.media_size
+msg.media_duration
+msg.media_width
+msg.media_height
+msg.media_sticker_emoji
+
+# Buttons
+msg.has_buttons?
+msg.buttons               # array of rows, each row is array of Types::Button
+
+# Actions
+msg.reply("text")
+msg.edit("new text", parse_mode: "html", buttons: buttons)
+msg.delete
+msg.forward(other_chat)
+msg.pin
+msg.download("/path/to/save") { |downloaded, total| ... }
+```
+
+### Button
+
+```ruby
+button.text
+button.callback_data      # raw bytes
+button.data_str           # callback_data as UTF-8 string
+button.url
+button.switch_inline
+button.callback?
+button.url?
+```
+
+### User
+
+```ruby
+user.id
+user.first_name
+user.last_name
+user.username
+user.phone
+user.bot?
+user.full_name            # "first last"
+```
+
+### Dialog
+
+```ruby
+dialog.id
+dialog.name
+dialog.peer_type
+dialog.unread_count
+dialog.last_message_text
+```
+
+### Participant
+
+```ruby
+participant.id
+participant.first_name
+participant.last_name
+participant.username
+participant.full_name
+```
+
+### Peer
+
+```ruby
+peer.id
+peer.name
+peer.peer_type
+```
+
+### Permissions
+
+```ruby
+perms.is_admin
+perms.is_creator
+perms.is_banned
+perms.has_default_permissions
+perms.admin?
+perms.creator?
+perms.banned?
+```
+
+## Errors
+
+All errors inherit from `Grammerb::Errors::Error`.
+
+```
+Grammerb::Errors::Error
+  Grammerb::Errors::ConnectionError
+  Grammerb::Errors::AuthError
+  Grammerb::Errors::NotConnectedError
+  Grammerb::Errors::RPCError
+    Grammerb::Errors::FloodWait
+    Grammerb::Errors::UserNotFound
+    Grammerb::Errors::ChatWriteForbidden
+    Grammerb::Errors::PhoneNumberInvalid
+    Grammerb::Errors::SessionPasswordNeeded
+```
+
+RPCError has `code`, `message_text`, and `value` attributes. FloodWait has a `seconds` attribute with the wait time.
+
+FloodWait errors inside event handlers are automatically caught and slept on.
+
+```ruby
+begin
+  client.send_message(chat, "hello")
+rescue Grammerb::Errors::FloodWait => e
+  sleep e.seconds
+  retry
+rescue Grammerb::Errors::ChatWriteForbidden
+  puts "Can't write to this chat"
+rescue Grammerb::Errors::RPCError => e
+  puts "RPC error #{e.code}: #{e.message_text}"
+end
+```
+
+## Not yet implemented
+
+The following Telegram features are not currently supported:
+
+- Creating groups, channels, or supergroups
+- Editing chat title, description, or photo
+- Slow mode
+- Forum topics / threads
+- Message threads and replies-to-threads
+- Scheduled message management (listing, deleting scheduled messages)
+- Drafts
+- Voice and video calls
+- Stories
+- Contacts (import, add, delete, get contacts list)
+- Account management (update profile, change username, set privacy)
+- Two-factor authentication setup/management
+- Notification settings
+- Chat folders / filters
+- Sticker set management (create, add, remove sticker packs)
+- GIF search and saved GIFs
+- Payments and invoices
+- Bot menu button and commands management
+- Channel and group statistics
+- Sponsored messages
+- Message translations
+- Custom emoji
+- Takeout / data export
+- Telegram Premium features
+- Usernames (collectible usernames, multiple usernames)
+- Reactions list (who reacted)
+- Chat event log / admin log
+- Nearby users and chats
+- Password hint and recovery email
+
+These can still be accessed via `client.invoke_raw(request_bytes)` if you construct the TL request manually.
+
+## License
+
+MIT