roempro 0.1.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# ChangeLog
+
+## 0.1 (2012-10-14)
+
+  * Write documentation
+  * Improve url validation into Roempro::Config and Roempro::Request contructors
+  * Handle global session id as well as instance one
+  * Improve Roempro::Request intializer
+  * Make Roempro::Request and Roempro::Response inherit from Roempro::Class
+  * Split Roempro content into Roempro::Base and Roempro::Config
+  * Create Roempro::Class to override default class.
+  * Create Rails 3 initializer
+  * New method Roempro::Request#command to submit the command by submit a string
+  * Keep the last response into request
+  * Handle login stuff
+  * Improve exception handling
+  * Create Roempro::Response
+  * Create Roempro::Request class.
+  * Set up description and summary in gemspec file.
+  * Initialise roempro gem.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in roempro.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Révillon Loïk
+
+MIT License
+
+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,62 @@
+# Roempro - Oempro Ruby Wrapper
+
+It aims to easily deal with the API of a given Oempro application.
+
+## Installation
+
+### Using Gemfile
+
+Add this line to your application's Gemfile:
+
+    gem 'roempro'
+
+And then execute:
+
+    $ bundle install
+
+### By hand
+
+Install it yourself as:
+
+    $ gem install roempro
+
+## Usage
+
+### Rails 3
+
+After installing the gem, run the rails generator to populate the `config` and `config/initializers` directories
+
+    $ rails g roempro:install
+
+Set up the configuration in `config/roempro.yml`
+
+    production:
+        url:      path_to_oempro_api
+        username: oempro_user
+        password: oempro_password
+
+This will set up a default configuration use by Roempro.
+
+**Don't forget to restrict the permitions on the file.**
+
+    $ chmod 600 config/roempro.yml
+
+### Ruby and others frameworks
+
+The default configuration can also be set using Roempro::Config object, as
+
+    irb > Roempro::Config.load_from_hash :url => "path_to_oempro",
+                                         :username => "oempro_user",
+                                         :password => "oempro_password"
+
+### All cases
+
+The configuration can be set dynamicly, using the Roempro::Request constructor. *Useless if you set up Roempro::Config*
+
+    request = Roempro::Request.new :url => "path_to_oempro", :username => "oempro_user", :password => "oempro_password"
+
+Then, actually perform the request. For instance, retrieve all campaigns
+
+    request.get_campaigns
+
+**See the documentation for an advanced usage.**

data/README.rdoc

@@ -0,0 +1,61 @@
+= Roempro - Oempro Ruby Wrapper
+
+It aims to easily deal with the API of a given Oempro application.
+
+== Installation
+
+=== Using Gemfile
+
+Add this line to your application's Gemfile:
+
+    gem 'roempro'
+
+And then execute:
+
+    $ bundle install
+
+=== By hand
+
+Install it yourself as:
+
+    $ gem install roempro
+
+== Usage
+
+=== Rails 3
+
+After installing the gem, run the rails generator to populate the `config` and `config/initializers` directories
+
+  $ rails g roempro:install
+
+Set up the configuration in `config/roempro.yml`
+
+  production:
+    url:      path_to_oempro_api
+    username: oempro_user
+    password: oempro_password
+
+This will set up a default configuration use by Roempro.
+
+<b>Don't forget to restrict the permitions on the file.</b>
+
+  $ chmod 600 config/roempro.yml
+
+=== Ruby and others frameworks
+
+The default configuration can also be set using Roempro::Config object, as
+
+  irb > Roempro::Config.load_from_hash :url => "path_to_oempro", :username => "oempro_user", :password => "oempro_password"
+
+=== All cases
+
+The configuration can be set dynamicly, using the Roempro::Request constructor.
+*Useless if you set up Roempro::Config*
+
+  request = Roempro::Request.new :url => "path_to_oempro", :username => "oempro_user", :password => "oempro_password"
+
+Then, actually perform the request. For instance, retrieve all campaigns
+
+  request.get_campaigns
+
+<b>See the documentation for an advanced usage.</b>

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/rails/generators/roempro/install_generator.rb

@@ -0,0 +1,21 @@
+# -*- encoding : UTF-8 -*-
+
+module Roempro
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Create the Roempro gem configuration file at config/roempro.yml, and an initializer at config/initializers/roempro.rb'
+
+      def self.source_root
+        @roempro_source_root = File.expand_path("../templates", __FILE__)
+      end
+
+      def create_config_file
+        template 'roempro.yml', File.join('config', 'roempro.yml')
+      end
+
+      def create_initializer_file
+        template 'initializer.rb', File.join('config', 'initializers', 'roempro.rb')
+      end
+    end
+  end
+end

data/lib/rails/generators/roempro/templates/initializer.rb

@@ -0,0 +1,9 @@
+# -*- encoding : UTF-8 -*-
+
+require 'yaml'
+
+# Retrieve the values from config/roempro.yml
+config_values = YAML.load_file File.join(Rails.root, 'config', 'roempro.yml')
+
+# Load the configuration into Roempro
+Roempro::Config.load_from_hash config_values[Rails.env.to_s]

data/lib/rails/generators/roempro/templates/roempro.yml

@@ -0,0 +1,14 @@
+test:
+  url: PATH_TO_OEMPRO
+  username: USER
+  password: PASSWORD
+
+development:
+  url: PATH_TO_OEMPRO
+  username: USER
+  password: PASSWORD
+
+production:
+  url: PATH_TO_OEMPRO
+  username: USER
+  password: PASSWORD

data/lib/roempro/base.rb

@@ -0,0 +1,34 @@
+# -*- encoding : UTF-8 -*-
+
+##
+# Roempro, a shortcut for Ruby Oempro, is a Ruby wrapper for the Oempro API,
+# which provide a way to deal with the API easily.
+#
+# It's splited into mutiples sub-classes :
+# * Roempro::Base
+# * Roempro::Config
+# * Roempro::Request
+# * Roempro::Response
+#
+# Actually, Roempro::Class is also available but only used internaly, to give
+# more power to the Ruby class.
+#
+# Roempro::Base is responsible to give the commun stuff and hold some global
+# informations. Roempro::Config is responsible to hold the default
+# configuration. It give a way to efficiently init Roempro in Rails 3, with
+# intializers. Roempro::Request is responsible to handle what is needed to
+# actually deal with the API. It also provide severals other abilities.
+# Roempro::Response is responsible to store the API response. More, it yields
+# means to easily acces to the response component.
+module Roempro
+
+  ##
+  # Hold few informations used by the Roempro's components.
+  #
+  # For instance, it keep in mind the session_id when the user is logged in
+  # the API. Thus, all new Roempro::Request object will used this session_id,
+  # unless explicitly told them to not use it.
+  class Base < Roempro::Class
+    cattr_accessor :session_id
+  end
+end

data/lib/roempro/class.rb

@@ -0,0 +1,100 @@
+# -*- encoding : UTF-8 -*-
+
+module Roempro
+
+  ##
+  # Few improvements appended to the default Ruby *class*. This aim to be used
+  # by the others Roempro's components, to provide them tools to help with
+  # development.
+  #
+  # To achieve this, the Roempro component must inhérite from this specific
+  # Roempro::Class.
+  class Class
+
+    ##
+    # Create the reader accessors for the given attributes.
+    #
+    # <b>Planed to be used by the inherited class.</b>
+    #
+    # === Parameters
+    # [Array]
+    #   Named variables which required the accessors to be made.
+    #
+    # === Examples
+    #
+    #   Roempro.module_eval do
+    #     class SomeClass < Roempro::Class
+    #       cattr_reader :var
+    #     end
+    #   end
+    #
+    #   > Roempro::SomeClass.var
+    #     => nil
+    def self.cattr_reader(*attributes)
+      attributes.map!(&:to_sym).each do |attr|
+        class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+          @@#{attr} = nil unless defined? @@#{attr}
+
+          def self.#{attr}
+            @@#{attr}
+          end
+        EOS
+      end
+    end
+
+    ##
+    # Create the writer accessors for the given attributes.
+    #
+    # <b>Planed to be used by the inherited class.</b>
+    #
+    # === Parameters
+    # [Array]
+    #   Named variables which required the accessors to be made.
+    #
+    # === Examples
+    #
+    #   Roempro.module_eval do
+    #     class SomeClass < Roempro::Class
+    #       cattr_writer :var
+    #     end
+    #   end
+    #
+    #   > Roempro::SomeClass.var = "Hello world!"
+    #     => "Hello world!"
+    def self.cattr_writer(*attributes)
+      attributes.map!(&:to_sym).each do |attr|
+        class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+          @@#{attr} = nil unless defined? @@#{attr}
+
+          def self.#{attr}=(value)
+            @@#{attr} = value
+          end
+        EOS
+      end
+    end
+
+    ##
+    # Create both reader/writer accessors for the given attributes.
+    #
+    # <i>See cattr_reader and cattr_writer, to learn more.</i>
+    #
+    # <b>Planed to be used by the inherited class.</b>
+    #
+    # === Examples
+    #
+    #   Roempro.module_eval do
+    #     class SomeClass < Roempro::Class
+    #       cattr_reader :var
+    #     end
+    #   end
+    #
+    #   > Roempro::SomeClass.var = "Hello world!"
+    #     => "Hello world!"
+    #   > Roempro::SomeClass.var
+    #     => "Hello world!"
+    def self.cattr_accessor(*attributes)
+      cattr_reader *attributes
+      cattr_writer *attributes
+    end
+  end
+end

data/lib/roempro/config.rb

@@ -0,0 +1,45 @@
+# -*- encoding : UTF-8 -*-
+
+module Roempro
+  class Config < Roempro::Class
+    cattr_reader :url, :username, :password
+
+    ##
+    # Load the default configuration into Roempro::Config.
+    #
+    # Once the default configuration loaded into this object, all new
+    # Roempro's components will use those informations to configure
+    # themself. Unless a specific configuration is provide at creation.
+    #
+    # === Parameters
+    # [Hash]
+    #   [:url]
+    #     Define the path to the desired Oempro API
+    #   [:username]
+    #     The username to use for login
+    #   [:password]
+    #     The user's password
+    def self.load_from_hash(params={})
+      params = Hash[params.map {|k,v| [k.to_sym,v] }]
+
+      @@username = params[:username].to_s if params[:username]
+      @@password = params[:password].to_s if params[:password]
+      @@url = if params[:url]
+        if uri = URI.parse(params[:url]) and
+           uri.instance_of? URI::HTTPS
+            raise ArgumentError, "Roempro::Request doesn't support SSL yet"
+        end
+        if uri.instance_of? URI::Generic
+          "http://" + params[:url].to_s
+        elsif uri.kind_of?  URI::HTTP
+          params[:url].to_s
+        end
+      end
+
+      return self if @@url or @@username or @@password
+
+    rescue URI::Error, ArgumentError => message
+      puts message
+    end
+  end
+end

data/lib/roempro/request.rb

@@ -0,0 +1,200 @@
+# -*- encoding : UTF-8 -*-
+
+require "net/http"
+require "uri"
+
+module Roempro
+  ##
+  # Entity which actually perform the request to the given Oempro API.
+  #
+  # It give a way to merely deal with the API handling all the undestood
+  # commands. Actually, it build the request chain from the methods names and
+  # the hash submited as argument.
+  #
+  # For instance, to fetch all emails :
+  #
+  #   req = Roempro::Request.new
+  #   # => #<Roempro::Request>
+  #   req.get_emails    # Will actually retrieve all emails.
+  class Request < Roempro::Class
+
+    ##
+    # Return a new Roempro::Request object
+    #
+    # Paramters are optionals. Those which are missing will
+    # be got from Roempro::Config.
+    #
+    # === Parameters
+    # [Hash]
+    #   [:url]
+    #     Define the path to the desired Oempro API
+    #   [:username]
+    #     The username to use for login
+    #   [:password]
+    #     The user's password
+    def initialize(params={})
+      @username = params[:username].to_s if params[:username]
+      @password = params[:password].to_s if params[:password]
+      @@url = if params[:url]
+        if uri = URI.parse(params[:url]) and
+           uri.instance_of? URI::HTTPS
+            raise ArgumentError, "Roempro::Request doesn't support SSL yet"
+        end
+        if uri.instance_of? URI::Generic
+          "http://" + params[:url].to_s
+        elsif uri.kind_of?  URI::HTTP
+          params[:url].to_s
+        end
+      end
+
+      if @url or @username or @password
+        @session_id = nil
+      end
+
+    rescue URI::Error, ArgumentError => message
+      puts message
+    end
+
+    ##
+    # Fallback to request a command to the Oempro API.
+    #
+    # For the most commands, just call them using the <i>method *to*
+    # command</i> pattern (see method_missing) should work fine. Nevertheless, few command in the
+    # Oempro API just cannot be send by this way, because of how
+    # Roempro::Request compute a called method to a proper command name.
+    #
+    # === Parameters
+    # [String]
+    #   The command name, as defined in the Oempro API documentation.
+    # [Hash]
+    #   Parameters to submit with the command.
+    def command(command_name, *args)
+      unless args.flatten.compact.empty? or args.flatten.first.kind_of? Hash
+        raise ArgumentError, "#{self.class}##{command_name.to_s} only accept hash argument"
+      end
+
+      login unless logged_in?
+
+      if logged_in?
+        perform (args.flatten.first || {}).merge :command => command_name
+      end
+
+    rescue ArgumentError => message
+      puts message
+    end
+
+    ##
+    # Provide to the Object's user a flexible way to command to the Oempro API.
+    #
+    # It work with the following pattern :
+    #
+    #   Romepro::Request#given_command
+    #   # Use "Command.Given" as command to send to the Oempro API
+    #
+    # === Examples
+    #
+    #   > req = Roempro::Request.new
+    #     => #<Roempro::Request>
+    #   > req.get_emails    # GET [...]api.php?command=Emails.Get[...]
+    def method_missing(method_id, *args)
+      unless args.empty? or args.first.kind_of? Hash
+        raise ArgumentError, "#{self.class}##{method_id.to_s} only accept hash argument"
+      end
+
+      command(method_id.to_s.split('_').map(&:capitalize).reverse.join('.'), args)
+
+    rescue ArgumentError => message
+      puts message
+    end
+
+    ##
+    # Return the last response answered by the Oempro API
+    #
+    # === Return
+    # Roempro::Response
+    def last_response
+      @last_response
+    end
+
+    ##
+    # Tell if Roempro is currently logged in the Oempro API.
+    #
+    # If the current object has been created with a specific url, username or
+    # password else than the default configuration, then, it check the
+    # <i>session id</i> stored within this Roempro::Request object.
+    #
+    # Else, it look for <i>session id</i> kept into Roempro::Base.
+    def logged_in?
+      if defined? @session_id
+        @session_id ? true : false;
+      else
+        Base.session_id ? true : false;
+      end
+    end
+
+    ##
+    # Log into the Oempro API
+    #
+    # If the given url, username or password are different from the default
+    # ones, then it use them and the returned <i>session id</i> is stored
+    # within this Roempro::Request object.
+    #
+    # Else, the <i>session id</i> is kept into Roempro::Base
+    def login
+      unless logged_in?
+        unless (@username and @password) or (Config.username and Config.password)
+          raise ArgumentError, "You have to submit your username and password to log into Oempro"
+        end
+
+        perform :command => "User.Login",
+                :username => @username || Config.username,
+                :password => @password || Config.password,
+                :disablecaptcha => true
+
+        unless @last_response.success
+          raise RuntimeError, @last_response.error_text.join("\n")
+        end
+
+        if defined? @session_id
+          @session_id = @last_response.session_id
+        else
+          Base.session_id = @last_response.session_id
+        end
+      end
+
+    rescue ArgumentError => message
+      puts message
+    end
+
+    private
+
+      ##
+      # Perform a request to the Oempro API.
+      #
+      # It look for specific url, username or password and use it. Else, it
+      # look for the default configuration.
+      #
+      # === Parameters
+      # [Hash]
+      #   Parameters to submit with the command
+      #
+      # === Return
+      # Roempro::Response
+      def perform(query={})
+        unless @url or Config.url
+          raise ArgumentError, "Unable to perform the request : Uknown URL to Oempro"
+        end
+        unless query.nil? or query.kind_of? Hash
+          raise ArgumentError, "Unable to perform the request : params have to be a hash"
+        end
+
+        query ||= {}
+        query.merge! :sessionid => @session_id || Base.session_id, :responseformat => 'JSON'
+
+        uri = URI(@url || Config.url)
+        uri.query = URI::encode_www_form query
+
+        @last_response = Roempro::Response.new(Net::HTTP.get_response(uri))
+      end
+  end
+end

data/lib/roempro/response.rb

@@ -0,0 +1,67 @@
+# -*- encoding : UTF-8 -*-
+
+require 'net/http'
+require 'json'
+
+module Roempro
+
+  ##
+  # Handle the response from Oempro API.
+  #
+  # It allow to easly access to the response parts.
+  #
+  # <b>Only work with JSON formated response!</b>
+  class Response < Roempro::Class
+
+    ##
+    # Create a new Roempro::Response object.
+    #
+    # === Parameters
+    # <b>URI::HTTPResponse</b>
+    def initialize(http_response)
+      unless http_response.kind_of? Net::HTTPResponse
+        raise ArgumentError, "#{self.class}#new only support Net::HTTPResponse as input"
+      end
+
+      @response = JSON.parse(http_response.body)
+      @response['HttpSuccess'] = http_response.is_a? Net::HTTPSuccess
+      @response = Hash[@response.map { |k,v| [k.downcase, v] }]
+
+    rescue ArgumentError => message
+      puts message
+    rescue JSON::ParserError
+      # Report the exception message ?
+      puts "JSON parser fail to compute the API's response"
+    end
+
+    ##
+    # As well as Roempro::Request, Roempro::Response return a response part
+    # according the called method.
+    #
+    # The followed pattern is simple. To access to a response part just call
+    # it.
+    #
+    # ==== Examples
+    #
+    #   > req = Roempro::Request.new
+    #     => #<Roempro::Request>
+    #   > res = req.get_emails
+    #     => #<Roempro::Response @response={"success"=>true,
+    #        #  "errorcode"=>0, "errortext"=>"", "totalemailcount"=>1,
+    #        #  "emails"=>[{"EmailID"=>"1"[...]}], "httpsuccess"=>true}>
+    #   > res.success
+    #     => true
+    #   > res.totalemailcount
+    #     => 1
+    def method_missing(method_id, *args)
+      if args.any?
+        raise ArgumentError, "#{self.class}##{method_id.to_s} doesn't accept any agument"
+      end
+
+      @response[method_id.to_s.split('_').join('')]
+
+    rescue ArgumentError => message
+      puts message
+    end
+  end
+end

data/lib/roempro/version.rb

@@ -0,0 +1,7 @@
+# -*- encoding : UTF-8 -*-
+
+module Roempro
+  ##
+  # The current version of Roempro.
+  VERSION = "0.1.1"
+end

data/lib/roempro.rb

@@ -0,0 +1,9 @@
+# -*- encoding : UTF-8 -*-
+
+require "roempro/class"
+
+require "roempro/base"
+require "roempro/config"
+require "roempro/version"
+require "roempro/request"
+require "roempro/response"

data/roempro.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'roempro/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "roempro"
+  gem.version       = Roempro::VERSION
+  gem.authors       = ["Nilsine", "Révillon Loïk", "Jean-philippe Lannoy"]
+  gem.email         = ["info@nilsine.fr"]
+  gem.description   = "Deal with a given Oempro application API. Handle about subscribers, campaigns and emails"
+  gem.summary       = "Ruby wrapper for Oempro API"
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.has_rdoc      = true
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: roempro
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- Nilsine
+- Révillon Loïk
+- Jean-philippe Lannoy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-24 00:00:00.000000000 Z
+dependencies: []
+description: Deal with a given Oempro application API. Handle about subscribers, campaigns
+  and emails
+email:
+- info@nilsine.fr
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- README.rdoc
+- Rakefile
+- lib/rails/generators/roempro/install_generator.rb
+- lib/rails/generators/roempro/templates/initializer.rb
+- lib/rails/generators/roempro/templates/roempro.yml
+- lib/roempro.rb
+- lib/roempro/base.rb
+- lib/roempro/class.rb
+- lib/roempro/config.rb
+- lib/roempro/request.rb
+- lib/roempro/response.rb
+- lib/roempro/version.rb
+- roempro.gemspec
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Ruby wrapper for Oempro API
+test_files: []