xasin-telegram 0.2.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 25c7030241f3f7f6eb094897f5175c49a177e299
-  data.tar.gz: 9d335a41200777ead31dad505e059d3a9ae726c1
+  metadata.gz: c2ccbe2c5e19793d17753159a59acf85dec93d22
+  data.tar.gz: e65517722e9e6e3899465f549e09098ae2f1afdc
 SHA512:
-  metadata.gz: 6fe1d6ce851631e0460bba3b843eef7fbf3583bff045bd854870c9cf1cb8526c8b300e5a793d7e13e5c8ebbf22a1fc926bf0727a7f13b7d243faf35878c26685
-  data.tar.gz: 2dc0c584e4e5e4b829d0f8c8b12ef0664a78326f6d5d7769fdfbb4da53bd2c3a47688137ea17f39bd12042bb980b65a1770629307b7b086bcfb099801b9eddbf
+  metadata.gz: 9c47bcc7ca20f4601a05124f54e5cbd6401830549ff498dd56bd288c93144460ac066e2a6034a1b82ccec54e948865c04b0b0d5316264c2f46459b0b84de541a
+  data.tar.gz: 9b5b1f2572223209dc066acf0bac202c6ba1f758eec3308d9486b1ec063ab24e36ee35b7e642a1a33f2f8f0e359c887506c6993fc8afa935d6693aba720e3bfd

data/README.md

@@ -8,8 +8,31 @@ My gem doesn't include all functionality, but aims to provide a somewhat simpler
 interaction with a small number (or just a single) of users.
 I mainly use it for my own smart home system, to easily send and receive messages, but not much more.
 
+## MQTT-Mode (Preferred)
+The main mode of using this gem would be via the MQTT Adapter system.
+It translates a lot of commonly used functionality into an asynchronous MQTT API, allowing other parts of your code, but also embedded devices like ESPs to very easily interface with the Telegram bot.
+
+*Note:* A MQTT server is not needed! The "virtual" MQTT Server `MQTT::Testing::SubHandler` can be used too!
+
+Setting up the system is fairly easy:
+
+```Ruby
+require 'xasin/telegram.rb'
+require 'xasin/telegram/MQTT_Adapter.rb'
+
+# Create the HTTP core, which will handle all the communication to the REST api
+httpCore = Xasin::Telegram::HTTPCore.new(APIKEY);
+
+# Now create the MQTT interface.
+mqttAdapter = Xasin::Telegram::MQTT::Server.new(httpCore, mqtt);
+```
+
+This exposes the Telegram Bot's interface functions to the "Telegram/#" tree.
+
+Incoming messages will be published to
+
 ## Single-User mode
-The main element of this gem is the single user mode.
+Another way to use the HTTP-Core is by only looking at a single user.
 It discards messages of all users except one, and provides a simple "send" and "on_message" interface:
 
 ```Ruby

data/lib/xasin/bad_config.yml

@@ -0,0 +1,7 @@
+Telegram:
+   Key: 1020712802:AAHNFf0Ofqo1pFA2f4JYgCvaHEqPWjmffBY
+   Permissions:
+      Admin:
+         - can_total_recall
+   Users:
+      87816854: {}

data/lib/xasin/bad_test.rb

@@ -0,0 +1,38 @@
+
+
+require_relative 'telegram/Handler.rb'
+require 'yaml'
+
+opts = YAML.load(File.read('bad_config.yml'));
+
+puts "My opts are #{opts}"
+
+handler = Xasin::Telegram::Handler.from_options(opts['Telegram'])
+
+$xasin = handler[87816854]
+msg = $xasin.send_message "Smol test :>"
+
+handler.on_command 'give_me_perm' do |msg|
+	permission = /\/give_me_perm (.*)/.match(msg.text)[1]
+
+	msg.user.add_permission permission
+
+	msg.send_message "You now have the following permissions: #{msg.user.permissions}",
+		inline_keyboard: { "Good!" => "/give_me_perm sudo", "Recall!" => "/total_recall"}
+end
+
+handler.on_command 'total_recall', permissions: 'can_total_recall' do |msg|
+	msg.send_message "Yes, recalling!"
+end
+
+sleep 4
+
+msg.edit_text "NOT SO SMALL ANY MORE, AI?"
+
+sleep 2
+
+msg.delete!
+
+loop do
+	sleep 3
+end

data/lib/xasin/telegram.rb

@@ -1,3 +1,4 @@
 
 require_relative "telegram/HTTPCore.rb"
 require_relative "telegram/SingleUser.rb"
+require_relative "telegram/MQTT_Adapter.rb"

data/lib/xasin/telegram/Chat.rb

@@ -0,0 +1,87 @@
+
+module Xasin
+	module Telegram
+		class Chat
+			attr_reader :chat_id
+			attr_reader :str_id
+
+			attr_reader :casual_name
+
+			attr_reader :chat_obj
+
+			attr_reader :on_telegram_event
+
+			# Initialize a chat object.
+			# Call this to generate a new chat object. It will
+			# always have to be called with a Chat object, as returned by
+			# a message's "chat" field or the getChat function
+			def initialize(handler, chat_info)
+				@handler = handler;
+
+				@chat_id = chat_info[:id];
+				@str_id  = chat_info[:username] ||
+				           chat_info[:title]
+
+				@casual_name = @str_id;
+
+				@chat_obj = chat_info;
+
+				@on_telegram_event = []
+			end
+
+			# Send a message to this chat.
+			# @see Handler#send_message
+			def send_message(text, **options)
+				@handler.send_message(self, text, **options);
+			end
+
+			# Add a new message callback.
+			# Similar to the Handler's function, but only applies
+			# to this chat's messages. Especially nice for one-on-one bots.
+			# @see Handler#on_message
+			def on_message(regexp = nil, &block)
+				raise ArgumentError, 'Block must be given!' unless block_given?
+
+				out_evt = OnMessage.new({ block: block, regexp: regexp });
+				@on_telegram_event << out_evt
+
+				out_evt
+			end
+
+			# Add a command callback.
+			# Equivalent to {Handler#on_command}, but will only be called
+			# on commands issued in this chat.
+			def on_command(command, **options, &block)
+				raise ArgumentError, 'Block must be given!' unless block_given?
+
+				options[:block] = block
+				options[:command] = command
+
+				out_evt = OnCommand.new(options);
+				@on_telegram_event << out_evt
+
+				out_evt
+			end
+
+			# Return a Telegram mention link.
+			# Can be inserted into a Telegram HTML formatted message, and
+			# allows people to click on the name.
+			def tg_mention
+				"<a href=\"tg://user?id=#{@chat_id}\">@#{@str_id}</a>"
+			end
+
+			# Return a more human-friendly name for the chat.
+			def casual_name
+				@str_id
+			end
+
+			def to_i
+				@chat_id
+			end
+			
+			def to_s
+				@casual_name
+			end
+		end
+	end
+end

data/lib/xasin/telegram/GroupingAdapter.rb

@@ -0,0 +1,273 @@
+
+require_relative 'HTTPCore.rb'
+
+module Xasin
+	module Telegram
+		# This class handles translating the sometimes a bit interesting
+		# Telegram API data to more usable types.
+		# It also handles the translation of User-IDs to the Usernames,
+		# and provides "Grouping IDs" to make it easier to edit, reply to, and
+		# delete messages
+		# It also exposes a much neater way of constructing inline keyboards.
+		class GroupingAdapter
+			attr_accessor :usernameList
+			attr_reader   :groupIDList
+
+			attr_reader :testLastUID
+			attr_reader :testLastData
+
+			def initialize(httpCore)
+				# Check if we already have a HTTPCore, else create one
+				@httpCore = if(httpCore.is_a? Telegram::HTTPCore)
+						httpCore;
+					else
+						Telegram::HTTPCore.new(httpCore);
+					end
+				@httpCore.attach_receptor(self);
+
+				_reset();
+			end
+
+			def _reset()
+				# Hash {username => ChatID}
+				@usernameList 	= Hash.new();
+				# Hash {ChatID => {GroupID => MessageID}}
+				@groupIDList 	= Hash.new do |hash, key|
+					hash[key] = Hash.new;
+				end
+			end
+
+			# Tested in ts_group_adapter/test_keyboard_build
+			def _process_inline_keyboard(keyboardLayout, gID = nil)
+				# Return unless we have a structure we can form into a keyboard
+				return nil unless (keyboardLayout.is_a? Array or keyboardLayout.is_a? Hash)
+
+				# Make sure the structure of keyboardLayout is [{}] or [[]]
+				if(keyboardLayout.is_a? Hash)
+					keyboardLayout = [keyboardLayout]
+				elsif(not (keyboardLayout[0].is_a? Array or keyboardLayout[0].is_a? Hash))
+					keyboardLayout = [keyboardLayout]
+				end
+
+				outData = Array.new();
+
+				# Iterate through the rows of keyboards
+				keyboardLayout.each do |row|
+					newRow = Array.new();
+
+					# Create the INLINE KEY button elements
+					row.each do |key, val|
+						cbd = {i: gID, k: (val or key)};
+						newRow << {text: key, callback_data: cbd.to_json}
+					end
+
+					# Add the new row to the array of rows
+					outData << newRow;
+				end
+
+				# Return the ready reply_markup element
+				return {inline_keyboard: outData};
+			end
+
+			# Processes messages received through MQTT/Custom input
+			# It takes care of setting a few good defaults (like parse_mode),
+			# deletes any old messages of the same GroupID (if requested),
+			# and stores the new Message ID for later processing
+			# @param data [Hash] The message packet to be sent to Telegram
+			#   The "text" field is always required. Optional fields are:
+			#   - gid: Grouping-ID for later editing/deleting/replying to
+			#   - replace: true/false whether or not the old GID-Tagged message should be deleted
+			#   - overwrite: Similar to replace, but instead of re-sending, it only edits the old message
+			#   - silent: Sets the "disable_notification" flag
+			#   - inline_keyboard: Hash of inline keyboard buttons (Button-text as key, button reply as value)
+			# @param uID [Integer,String] The user-id as received from the MQTT Wildcard.
+			#   Can be a username defined in @usernameList, or the raw Chat ID
+			# Tested in ts_mqtt/test_send
+			def _handle_send(data, uID)
+				# Resolve a saved Username to a User-ID
+				uID = @usernameList[uID] if(@usernameList.key? uID)
+				return if (uID = uID.to_i) == 0; # Return if a unknown Username was used
+
+				gID = data[:gid];
+
+				# Check if a GroupID is present and a former message is known
+				if(gID and @groupIDList[uID][gID])
+					if(data[:replace])
+						_handle_delete(gID, uID)
+					elsif(data[:overwrite])
+						_handle_edit(data, uID);
+						return; # After editing, no new message should be sent!
+					end
+				end
+
+				# Lay out all mandatory parameters for sendMessage request
+				outData = {
+					chat_id: 	uID,
+					parse_mode: (data[:parse_mode] or "Markdown"), # Markdown parse mode is just nice
+					text:			data[:text]
+				}
+
+				# Check if the message is meant to be sent without notification
+				if(data[:silent])
+					outData[:disable_notification] = true;
+				end
+
+				# Check if an inline keyboard layout is given, and parse that.
+				if((ilk = data[:inline_keyboard]))
+					outData[:reply_markup] = _process_inline_keyboard(ilk, gID);
+				end
+
+				reply = @httpCore.perform_post("sendMessage", outData);
+				return unless reply[:ok]	# Something was wrong about our message layout
+				# TODO Add a proper error handler here.
+
+				# If a GroupID was given, save the sent message's ID
+				@groupIDList[uID][gID] = reply[:result][:message_id] if(gID);
+			end
+
+			# Edits an already known message. Takes arguments similar to _handle_send
+			# @param data [Hash] The message to be edited. GID must be set, and optionally
+			#   a inline keyboard markup or a new message text must be provided.
+			# @param uID [Integer,String] The user-id as received from the MQTT Wildcard.
+			#   Can be a username defined in @usernameList, or the raw Chat ID
+			def _handle_edit(data, uID)
+				# Resolve a saved Username to a User-ID
+				uID = @usernameList[uID] if(@usernameList.key? uID)
+				return if (uID = uID.to_i) == 0; # Return if a unknown Username was used
+
+				# Fetch the target MessageID - Return if none is present
+				return unless mID = @groupIDList[uID][data[:gid]]
+
+				# Lay out all mandatory arguments for the edit POST
+				outData = {
+					chat_id: uID,
+					message_id: mID,
+				};
+
+				# If a inline keyboard was given, parse that.
+				if(ilk = data[:inline_keyboard])
+					outData[:reply_markup] = _process_inline_keyboard(ilk, data[:gid]);
+				end
+
+				if(data[:text]) # Check if text was given
+					outData[:text] = data[:text];
+					# Send the POST request editing the message text
+					@httpCore.perform_post("editMessageText", outData);
+				else
+					# Otherwise, only edit the reply markup (keyboard etc.)
+					@httpCore.perform_post("editMessageReplyMarkup", outData);
+				end
+			end
+
+			# Deletes a message marked by a given GID
+			# @param gid [String] The grouping-ID of the message to delete.
+			# @param uID [Integer, String] The User-ID (as defined in @usernameList, or
+			#    the raw ID), for which to delete.
+			def _handle_delete(data, uID)
+				# Resolve a saved Username to a User-ID
+				uID = @usernameList[uID] if(@usernameList.key? uID)
+				return if (uID = uID.to_i) == 0; # Return unless the username was known
+
+				# Fetch the real message ID held by a grouping ID
+				return unless mID = @groupIDList[uID][data]
+				@groupIDList[uID].delete(data); # Clear that ID from the list
+
+				# Perform the actual delete
+				@httpCore.perform_post("deleteMessage", {chat_id: uID, message_id: mID});
+			end
+
+			def on_message(data, uID)
+				@testLastUID  = uID;
+				@testLastData = data;
+			end
+
+			def on_command(data, uID)
+			end
+
+			def on_reply(data, uID)
+			end
+
+			def on_callback_pressed(data, uID)
+			end
+
+			# Handle an incoming message packet from the HTTP core
+			# @private
+			def handle_message(msg)
+				uID = msg[:chat][:id];
+				# Resolve the User-ID, if it's known.
+				if(newUID = @usernameList.key(uID))
+					uID = newUID
+				end
+
+				data = Hash.new();
+				# Only accept messages that contain text (things like keyboard replies
+				# are handled elsewhere).
+				return unless(data[:text] = msg[:text])
+
+				# See if this message was a reply, and if we know said reply under a group-id
+				if(replyMSG = msg[:reply_to_message])
+					data[:reply_gid] = @groupIDList[uID].key(replyMSG[:message_id]);
+				end
+
+				# Distinguish the type of message. If it starts with a command-slash,
+				# it will be excempt from normal processing.
+				# If it has a reply message ID that we know, handle it as a reply.
+				# Otherwise, simply send it off as a normal message.
+				if(data[:text] =~ /^\//)
+					on_command(data, uID)
+				elsif(data[:reply_gid])
+					on_reply(data, uID)
+				else
+					on_message(data, uID)
+				end
+			end
+
+			# Handle an incoming callback query (inline keyboard button press)
+			# as received from the HTTP Core
+			# @private
+			def handle_callback_query(cbq)
+				# Send out a callback query reply (i.e. Telegram now knows we saw it)
+				@httpCore.perform_post("answerCallbackQuery", {callback_query_id: cbq[:id]});
+
+				# Resolve the username, if we know it.
+				uID = msg[:message][:chat][:id];
+				if(newUID = @usernameList.key(uID))
+					uID = newUID
+				end
+
+				# Try to parse the data. This gem sets inline keyboard reply data to
+				# a small JSON, which identifies the GID and the key that was pressed.
+				begin
+					data = JSON.parse(cbq[:data], symbolize_names: true);
+				rescue
+					return;
+				end
+
+				data = {
+					gid:  data[:i],
+					key: data[:k],
+				}
+
+				# If the key ID starts with a command slash, treat it like a normal
+				# command. Has the benefit of making it super easy to execute already
+				# implemented actions as a inline keyboard
+				if(data[:key] =~ /^\//)
+					on_command({text: data[:key], gid: data[:gid]}, uID);
+				end
+				on_callback_pressed(data, uID);
+			end
+
+			# Handle incoming HTTP Core packets. Just send them to the appropriate
+			# handler function
+			def handle_packet(packet)
+				if(msg = packet[:message])
+					handle_message(msg);
+				end
+
+				if(cbq = packet[:callback_query])
+					handle_callback_query(cbq);
+				end
+			end
+		end
+	end
+end