porteo 0.1.0

data/README.markdown

@@ -0,0 +1,63 @@
+# Porteo
+A Ruby gem that send messages via any protocol/gateway with programable templates and emitters.
+
+# Usage
+All you have to do is to create a new Message object like this:
+
+    my_msg = Porteo::Message.new()
+
+    my_msg.configure do |m|
+      # set the template named foo
+      # The template must be set in the template path (./config/templates/ by default)
+      m.template = "foo"
+      # set the emitter named bar
+      # The emitter must be set in config path (./config/ by default)
+      # by default get the "default" profile in emitter
+      m.emitter = "bar"
+      # Set the protocol
+      m.protocol = "desired_protocol"
+    end
+
+Now you only have to set the params on the template (if you required it) like this:
+
+    my_msg.params = { :name_of_the_param => value_of_the_param }
+
+Or this:
+    
+    my_msg.name_of_the_param = value_of_the_param
+
+# Configuration Files
+The files that are strictly necesaries are: a emitter, and a template. Their construction are the folloing:
+
+## Emitter
+An emitter must be constructed using YAML like this:
+
+    :protocolName:
+      :profileName:
+        :configParam1: :valueParamSymbol
+        :configParamFoo: 'valueParamString'
+        :configParambar: 'etc'
+      :otherProfile:
+        :configParam: :value
+        :bar: 'foo'
+    :otherProtocol:
+      :profileName:
+        :protocolconfigparam: 'value'
+
+## Template
+A template file must be constructed using YAML + ERB like this:
+
+    :requires: [:parameterName]
+    :template:
+      :fieldOfTemplate: "This is a Example of a template file, a parameter must be given, its value is: <%= param[:parameterName] %>"
+
+The template file must be named with "templateName.protocolName", ONLY templateName must be given to the Message class to know which template to use.
+
+# About
+Porteo is developed by [NoSoloSoftware](http://nosolosoftware.biz).
+
+# License
+Porteo is Copyright 2011 NoSoloSoftware, it is free software.
+
+Porteo is distributed under GPLv3 license. More details can be found at COPYING file.
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/gateways/gateway.rb

@@ -0,0 +1,126 @@
+# Copyright 2011 NoSoloSoftware
+#
+# This file is part of Porteo.
+# 
+# Porteo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Porteo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Porteo. If not, see <http://www.gnu.org/licenses/>.
+
+# Porteo is an integrated message sending service.
+# It allows you to send messages by various protocols (sms, email, twitter)
+# using differents gateways (mensario, pony, twitter API). You can also
+# integrate new protocols and gateways for your favorite messenger 
+# service.
+module Porteo
+
+  # Base class to implement any gateway needed to connect protocols
+  # and sending service gems.
+  #
+  # It should not be used by itself but creating a child class which
+  # defines specific behavior based on a certain protocol and a gem.
+  class Gateway
+
+    # Set required connection parameters for a specific gateway.
+    # This class method creates a new instance method which overwritte
+    # connection_argument.
+    # @param [Array] argument Required connection arguments.
+    # @return [nil]
+    def self.connection_argument( *argument )
+      define_method( :connection_arguments ) do
+        argument
+      end
+    end
+
+    # Required connection parameters.
+    # Its define which fields have to be present in order to
+    # send a valid message.
+    # This method is overwritten dynamically when a child gateway
+    # class is created and self.connection_arguments is called.
+    # @return [Array] Required connection parameters.
+    def connection_arguments
+      []
+    end
+
+    # Create a new instance of a gateway.
+    # @param [Hash] gw_config Configuration options. This options
+    #   set the sending parameters not the content of the message.
+    def initialize( gw_config = {} )
+      @config = gw_config
+    end
+
+    # @abstract
+    # Send a message defined in parameter
+    # @param [Hash] message_sections Message content.
+    # @return [nil]
+    # @raise [Exception] This method is not meant to be call but to be overwritten.
+    # @note This method has to be overwritten.
+    def send_message( message_sections )
+      raise Exception, "Gateway Error. This method has to be overwritten. You are trying to send a message with a generic gateway."
+    end
+
+    # Initialize the send message process.
+    # Before sending the message it check if all required params are present.
+    # @param [Hash] message Message sections to be sent.
+    # @return [nil]
+    def init_send( message )
+      send_message_hook( message )
+    end
+
+    # PRIVATE METHODS
+    private
+
+    # Defines send message process.
+    # It first look for all required connection arguments
+    # and then it send the message.
+    # @param [Hash] message Message section to be sent.
+    def send_message_hook( message )
+      check_connection_arguments
+      send_message( message )
+    end
+
+    # Looks for a key in a specified hash.
+    # If an argument is not present, an ArgumentError is raised.
+    # @param [Hash] config Configuration hash.
+    # @param [Symbol] argument Key that should be contain by hash.
+    # @return [nil]
+    # @raise [ArgumentError] If the argument is not present in configuration hash.
+    def check_argument( config, argument )
+      raise ArgumentError, "Gateway Error. Too few arguments to connect." unless config[argument] != nil
+    end
+
+    # Checks the required connection parameters to any gateway.
+    # Those parameters are defined by class method connection_argument.
+    # @return [nil]
+    def check_connection_arguments
+      # Iterate over arguments
+      connection_arguments.each do |argument|
+
+        # If argument is a hash, we need to search for the parameter
+        # in a sublevel of config. That sublevel is defined by the hash
+        # key so there should be only one key. The value of that key is an
+        # array containing the sublevel arguments.
+        if argument.class == Hash
+          argument.values[0].each do |value|
+
+            # Once we know where and what look for, we do the check
+            check_argument( @config[argument.keys[0]], value )
+          end
+        else
+          
+          # Check the argument in top level configuration array.
+          check_argument( @config, argument )
+        end
+      
+      end
+    end
+  end
+end

data/lib/gateways/mensario_gateway.rb

@@ -0,0 +1,62 @@
+# Copyright 2011 NoSoloSoftware
+#
+# This file is part of Porteo.
+# 
+# Porteo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Porteo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Porteo. If not, see <http://www.gnu.org/licenses/>.
+
+require 'mensario'
+require 'gateways/gateway'
+
+# Porteo is an integrated message sending service.
+# It allows you to send messages by various protocols (sms, email, twitter)
+# using differents gateways (mensario, pony, twitter API). You can also
+# integrate new protocols and gateways for your favorite messenger 
+# service.
+module Porteo
+
+  # Gateway to use Mensario service
+  # In Porteo this class acts as a link between SMS protocol
+  # and Mensario gem
+  #
+  # This class inherits from Gateway and just overwrite
+  # the send_message method
+  class Mensario_gateway < Gateway
+
+    connection_argument :license,
+                        :password,
+                        :username
+
+    # Send the SMS using Mensario gem
+    # @param [Hash] msg The message sections to send
+    # @return [nil]
+    def send_message( msg )
+
+      Mensario.set_config do
+        Mensario.license( @config[:license] )
+        Mensario.username( @config[:username] )
+        Mensario.password( @config[:password] )
+      end
+      Mensario.send_message( {:text => msg[:text],
+                            :sender => msg[:sender],
+                            :code => msg[:code], 
+                            :phone => msg[:phone], 
+                            :timezone => msg[:timezone],
+                            :date => msg[:date] }
+                           )
+
+     end
+  end
+
+end
+

data/lib/gateways/pony_gateway.rb

@@ -0,0 +1,97 @@
+# Copyright 2011 NoSoloSoftware
+#
+# This file is part of Porteo.
+# 
+# Porteo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Porteo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Porteo. If not, see <http://www.gnu.org/licenses/>.
+
+require 'pony'
+require 'gateways/gateway'
+
+# Porteo is an integrated message sending service.
+# It allows you to send messages by various protocols (sms, email, twitter)
+# using differents gateways (mensario, pony, twitter API). You can also
+# integrate new protocols and gateways for your favorite messenger 
+# service.
+module Porteo
+ 
+  # Gateway to use an email service with Pony gems.
+  # In Porteo system, this class acts as a link between any email 
+  # protocol and Pony gem.
+  #
+  # This class inherits from Gateway class and just overwrite 
+  # the method send_message.
+  class Pony_gateway < Gateway
+    
+    connection_argument :via_options => [:address, :port, :user_name, :password]
+
+    # Options allowed for Pony API.
+    PONY_OPTIONS = [ 
+      :to, 
+      :cc, 
+      :bcc, 
+      :from, 
+      :body, 
+      :html_body, 
+      :subject, 
+      :charset,
+      :attachments,
+      :headers,
+      :message_id,
+      :sender
+      ]
+
+    # Via configuration options.
+    # The sending method is configured with these options.
+    VIA_OPTIONS = [
+      :address, 
+      :port, 
+      :user_name, 
+      :password, 
+      :enable_starttls_auto,
+      :authentication,
+      :domain,
+      :location,
+      :argument
+      ]
+    
+    # Send the message defined in parameter.
+    # @param [Hash] message_sections Differents parts of message. Allowed keys
+    #   are defined in PONY_OPTIONS.
+    # @return [nil]
+    def send_message( message_sections )
+      # Create options hash to Pony
+      pony_config = {}
+
+      # Recover data from template
+      # We look for each option defined before in the message content
+      PONY_OPTIONS.each do |opt|
+        pony_config[opt] = message_sections[opt] if message_sections[opt] != nil
+      end
+
+      # Recover data from send options
+      # First we get the via used to send the message
+      pony_config[:via] = @config[:via]
+
+      # Then we look for the other configuration options      
+      pony_config[:via_options] = {}
+      VIA_OPTIONS.each do |opt|
+        pony_config[:via_options][opt] = @config[:via_options][opt] if @config[:via_options][opt] != nil
+      end
+      
+      # Send the message
+      Pony.mail( pony_config )
+    end
+  end
+
+end

data/lib/gateways/twitter_gateway.rb

@@ -0,0 +1,57 @@
+# Copyright 2011 NoSoloSoftware
+#
+# This file is part of Porteo.
+# 
+# Porteo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Porteo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Porteo. If not, see <http://www.gnu.org/licenses/>.
+
+require 'twitter'
+require 'gateways/gateway'
+
+# Porteo is an integrated message sending service.
+# It allows you to send messages by various protocols (sms, email, twitter)
+# using differents gateways (mensario, pony, twitter API). You can also
+# integrate new protocols and gateways for your favorite messenger 
+# service.
+module Porteo
+
+  # Gateway to use Twitter service with Twitter gem.
+  # In Porteo this class acts as a link between any twitter protocol
+  # and Twitter gem.
+  #
+  # This class inherits from Gateway and just overwrite
+  # the send_message method.
+  class Twitter_gateway < Gateway
+
+    connection_argument :consumer_key, 
+                        :consumer_secret, 
+                        :oauth_token, 
+                        :oauth_token_secret
+
+    # Send the twitt using Twitter gem.
+    # @param [Hash] msg The message sections to send
+    # @return [nil]
+    def send_message( msg )
+      Twitter.configure do |config|
+        config.consumer_key = @config[:consumer_key]
+        config.consumer_secret = @config[:consumer_secret]
+        config.oauth_token = @config[:oauth_token]
+        config.oauth_token_secret = @config[:oauth_token_secret]
+      end
+
+     Twitter.update( msg[:body] ) 
+    end 
+  end
+
+end
+

data/lib/message/message.rb

@@ -0,0 +1,192 @@
+# Copyright 2011 NoSoloSoftware
+#
+# This file is part of Porteo.
+# 
+# Porteo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Porteo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Porteo. If not, see <http://www.gnu.org/licenses/>.
+
+require 'yaml'
+
+require 'protocols/twitter_protocol'
+require 'protocols/mail_protocol'
+require 'protocols/sms_protocol'
+
+# Porteo is an integrated message sending service.
+# It allows you to send messages by various protocols (sms, email, twitter)
+# using differents gateways (mensario, pony, twitter API). You can also
+# integrate new protocols and gateways for your favorite messenger 
+# service.
+module Porteo
+
+  # A message which will be send by any protocol and gateway.
+  # 
+  # The content of a message will be defined in a template, a file
+  # that contain differents sections each being one part of the message.
+  # This templates will be processed with ERB so its can contain ruby
+  # code to get more flexibility.
+  #
+  # The configuration options (for protocols and gateways) it set trought
+  # emitter files, special files in YAML format.
+  class Message
+    # A hash containing message sections defined in the template.
+    attr_reader :template_content
+    # An array containing required fields to define the template.
+    attr_reader :template_requires
+    
+    # The name of the protocol used to send the message.
+    attr_accessor :protocol
+    # Name of template used to send the message.
+    attr_accessor :template
+    # Parameters to set the fields defined in the template.
+    attr_accessor :template_params
+    # Path to configuration directory. It have to end in a slash.
+    attr_accessor :config_path
+    # Path to templates directory. It have to end in a slash.
+    attr_accessor :template_path
+    # The one who should receive the message.
+    attr_accessor :receiver
+    # Profile used to recover the gateway configuration.
+    attr_accessor :profile
+    # File used to load the configuration information.
+    attr_accessor :emitter
+
+
+    # Creates a new message.
+    # @param [String] emitter File used to load the configuration information.
+    # @param [String] protocol Protocol to be used (mail, sms, twitter).
+    # @param [String] profile Profile to load gateway information.
+    # @param [Hash] opts Options.
+    # @option opts :config_path ("./config/") Configuration path.
+    # @option opts :template_path ("./config/templates/") Templates path.
+    def initialize( emitter = "", protocol = "", profile = "default", template = "", opts = {} )
+      # config_path value should end in a trailing slash
+      opts[:config_path] ||= CONFIG_ROOT
+      @config_path = opts[:config_path]
+
+      # template_path value should end in a trailing slash
+      opts[:template_path] ||= TEMPLATES_ROOT
+      @template_path = opts[:template_path] 
+      
+      # Instance variables initilization
+      @template = template
+      @template_params = {}
+      @template_content = ""
+      @template_requires = []
+
+      @receiver = nil
+
+      # Assign instance variables
+      @emitter = emitter
+      @profile = profile
+      @protocol = protocol
+    end
+
+    # Convenience method to allow configuration options to be set in a block.
+    # @return [nil]
+    def configure
+      yield self
+    end
+
+    # Assign values to fields defined in the template.
+    # Overwrite all params set before.
+    # @param [Hash] params The keys are the fields defined in the
+    #   template which will be set to the hash value.
+    # @return [nil]
+    def set_template_params( params )
+      @template_params = params 
+    end
+
+    # Send a message using protocol, content and configuration set before.
+    # @return [nil]
+    # @raise [ArgumentError] If emitter file is not valid or if protocol is not defined.
+    def send_message
+      load_template( @template )
+      
+      # Load configuration information for the gateway
+      begin
+        config = YAML.load_file( "#{@config_path}#{@emitter}.emitter" )
+      rescue Errno::ENOENT
+        raise ArgumentError, "Message Error. Invalid emitter file '#{@config_path}#{@emitter}.emitter'. Check emitter name is correct. Emitter path can also be set throught config_path."   
+      end
+
+
+      raise ArgumentError, "Message Error. Profile '#{@profile}' not found." unless config[@protocol.to_sym][@profile.to_sym]
+
+      begin
+        # Creates a new instance of defined protocol
+        @protocol_obj = Porteo.const_get( "#{@protocol}_protocol".capitalize.to_sym ).new( config[@protocol.to_sym][@profile.to_sym] )
+      rescue NameError
+        raise ArgumentError, "Message Error. Undefined protocol. Check if '#{@protocol}_protocol.rb' is created and is valid."
+      end
+
+      # Set template values
+      @protocol_obj.set_template( @template_content, @template_requires )
+      @protocol_obj.set_template_params( @template_params )
+
+      # Set receiver
+      @protocol_obj.receiver = @receiver
+
+      # Send the message
+      @protocol_obj.send_message
+    end
+
+    # Method to see the complete message by sections, once it has been sent.
+    # @return [String] the message sections
+    def show_message
+      @protocol_obj.message unless @protocol_obj == nil
+    end
+
+    # Method missing is used to allow set params one by one.
+    # @param [Symbol] method param to be set.
+    # @param [Array] params params in the call.
+    # @param [Block] block block code in method.
+    def method_missing( method, *params, &block )
+      # We only allow one param to be passed
+      # so we check that only one param is passed
+      # and block is nil
+      # We want to use the prefered configuration style
+      # so we expect to use a call like this:
+      # my_obj.method_name = value
+      if method[-1] == "=" and params.size == 1 and block == nil
+        @template_params[method.to_s.chop.to_sym] = params[0]
+      else
+        super( method, params, block )
+      end
+    end
+
+    private
+    # Recover the information defined in a template file. The template is
+    # defined using YAML. It has the format of a hash, containing a key named
+    # requires, which value is an array of required fields for the template,
+    # and a key named template which contain the template itself.
+    # @param [String] template Template name to be used. Various templates may
+    #   have the same name (alert.mail, alert.sms, alert.twitter) but the one
+    #   named as protocol used will be used. So template name it just the first
+    #   part of the template filename.
+    # @return [nil]
+    def load_template( template )
+      begin
+        content = YAML.load_file( "#{@template_path}#{template}.#{@protocol}" )
+      rescue Errno::ENOENT
+        raise ArgumentError, "Message Error. Invalid template file '#{@template_path}#{template}.#{@protocol}'. Check if template name is correct and you are using a valid protocol. Template path can also be set throught template_path."
+      end
+      
+      if( content )
+        @template_content = content[:template].to_s
+        @template_requires = content[:requires] if content[:requires] != nil
+      end
+
+    end
+  end
+
+end

data/lib/porteo.rb

@@ -0,0 +1,32 @@
+# Copyright 2011 NoSoloSoftware
+#
+# This file is part of Porteo.
+# 
+# Porteo is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Porteo is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Porteo. If not, see <http://www.gnu.org/licenses/>.
+
+require 'message/message'
+
+# Porteo is an integrated message sending service.
+# It allows you to send messages by various protocols (sms, email, twitter)
+# using differents gateways (mensario, pony, twitter API). You can also
+# integrate new protocols and gateways for your favorite messenger 
+# service.
+module Porteo
+  # Default configuration path 
+  CONFIG_ROOT = "./config/"
+  # Default templates path
+  TEMPLATES_ROOT = "./config/templates/"
+  # Default locales path
+  LOCALES_ROOT = "./config/locales/"
+end