xnm-telegram 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b56c7a24cc65be03dda2eb188715b26d24bad941c90f2f6d98b1f95bd4f672b9
+  data.tar.gz: 7f2d2bf294f9152379c726f9a92868b562f30343019f21a5e597cfa26aa21d68
+SHA512:
+  metadata.gz: 561e100a3a128011b6df5e4e44e8d3e56aac6fb297f1b9ec987fd4fdf0c31b2c04ec1ba1cbdf471935dce9228f4df2e7f04b4ed4f3d327f17ca09bd31365b193
+  data.tar.gz: 87c30f5062838b931693acb00714dde8c6da9dc63a8745f9a6eeac24f24fb90b7641432839267cd26cb29106ccb98f8bf24b0481369b035f659faf218782e7ed

data/README.md

@@ -0,0 +1,64 @@
+
+# Xasin's simplifying Telegram gem
+This gem is mainly meant for personal use.
+Many of the existing Ruby gems for Telegram have all the functionality you want,
+but also require a fairly complex setup, and good knowledge of the Telegram API.
+
+My gem doesn't include all functionality, but aims to provide a somewhat simpler interface of
+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
+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
+require 'xasin/telegram.rb'
+
+# The HTTP "core" handles sending raw commands and getting updates, but not much more.
+httpCore = Xasin::Telegram::HTTPCore.new(APIKEY);
+
+# The SingleUser class handles the aforementioned sending/receiving of messages.
+# Its first argument is the Chat-ID it should use, which is NOT the user ID
+# To find it out you have to perform an update request to the Telegram API, send a message to your bot,
+# and get the Chat_ID from there.
+# I'm working on a better way >.>
+singleUser = Xasin::Telegram::SingleUser.new(CHAT_ID, httpCore);
+
+
+# From then, using the user is simple. Only text is required!
+returned_id = singleUser.send_message(TEXT, **args);
+
+# The ID that is returned can then be used to edit or delete the message:
+singleUser.edit_message(returned_id, NEW_TEXT);
+singleUser.delete_message(returned_id);
+
+# And to receive messages:
+singleUser.on_message do |message|
+	# Fetch the text from the message first!
+	text = message[:text];
+end
+```

data/lib/xnm/telegram.rb

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

data/lib/xnm/telegram/Chat.rb

@@ -0,0 +1,87 @@
+
+module XNM
+	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/xnm/telegram/GroupingAdapter.rb

@@ -0,0 +1,273 @@
+
+require_relative 'HTTPCore.rb'
+
+module XNM
+	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

data/lib/xnm/telegram/HTTPCore.rb

@@ -0,0 +1,128 @@
+
+require 'net/http'
+require 'json'
+require 'shellwords'
+
+module XNM
+module Telegram
+	# This class handles the direct connection to the Telegram API
+	# All it does is handle a receive loop with the fitting update IDs, as well
+	# as a rescue'd "perform post" message.
+	class HTTPCore
+		def initialize(apikey)
+			@apikey = apikey;
+
+			@lastUpdateID = 0;
+			# Start the receive loop. Shouldn't crash, but if it does we
+			# want to know.
+			@receiveThread = Thread.new do
+				receive_loop();
+			end
+			@receiveThread.abort_on_exception = true
+
+			# Receptors are class instances that will receive updates
+			# from the HTTP update connection
+			@receptors = Array.new();
+		end
+
+		private def _double_json_data(data)
+			return {} unless data
+
+			out_data = {}
+			# JSON-Ify nested Hashes and Arrays to a String before the main
+			# POST request is performed. Needed by Telegram, it seems.
+			data.each do |key, val|
+				if(val.is_a? Hash or val.is_a? Array)
+					out_data[key] = val.to_json
+				else
+					out_data[key] = val;
+				end
+			end
+
+			out_data
+		end
+
+		private def _raw_post(addr, data)
+			d_str = Shellwords.escape(data.to_json)
+
+			response = `curl -s -X POST -H "Content-Type: application/json" -d #{d_str} "#{addr}"`
+
+			JSON.parse(response, symbolize_names: true)
+		end
+		# Perform a POST request.
+		# @param method [String]  The Telegram bot API method that should be called
+		# @param data [nil, Hash] The data to be sent with the command.
+		#   Caution, any nested Hashes and Arrays will be converted to JSON
+		#   BEFORE the Hash itself is also JSON-ified. Telegram apparently
+		#   needs this to work.
+		def perform_post(method, data = nil)
+			call_address = "https://api.telegram.org/bot#{@apikey}/#{method}"
+
+			# Rescue-construct to prevent a HTTP error from
+			# crashing our system.
+			timeoutLen = data[:timeout] if data.is_a? Hash
+			timeoutLen ||= 4;
+			retryCount = 0;
+			begin
+				Timeout.timeout(timeoutLen) do
+					return _raw_post(call_address, _double_json_data(data));
+				end
+			rescue
+				retryCount += 1;
+				return {} if retryCount >= 3;
+
+				sleep 0.5;
+				retry
+			end
+		end
+
+		def feed_receptors(data)
+			# Hand it out to the receptors
+			@receptors.each do |r|
+				begin
+					r.handle_packet(data);
+				rescue => e
+					warn "Error in repector: #{e}"
+					warn e.backtrace.join("\n");
+				end
+			end
+		end
+
+		# Handle receiving of the data from Telegram API
+		# This is done via the "getUpdates" HTTP Request, with a timeout
+		# of 20s
+		# Update-ID offset is handled automagically by the system, so you needn't
+		# worry about it.
+		def receive_loop()
+			loop do
+				begin
+					# Perform the update request
+					packet = perform_post("getUpdates", {timeout: 20, offset: @lastUpdateID + 1})
+
+					next unless packet[:ok];
+					# Check if there even was a message sent by Telegram
+					# Due to the 20s timeout, a zero-length reply can happen
+					next if packet[:result].length == 0;
+
+					# Handle each result individually.
+					packet[:result].each do |data|
+						hUpdateID = data[:update_id].to_i
+						# Calculate the maximum Update ID (for the offset "getUpdates" parameter)
+						@lastUpdateID = [hUpdateID, @lastUpdateID].max
+
+						feed_receptors data
+					end
+				rescue
+					sleep 1
+					retry
+				end
+			end
+		end
+
+		# TODO check if the class supports handle_packet
+		def attach_receptor(receptorClass)
+			@receptors << receptorClass;
+		end
+	end
+end
+end