bluevia 1.0

data/LICENSE.LGPLv3

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions. 
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version. 
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/License_Bluevia.txt

@@ -0,0 +1,22 @@
+
+
+#################################################################################
+#                                                                               #
+#                                                                               #
+# This file is part of Bluevia Ruby SDK.                                        #
+#                                                                               # 
+# Bluevia Ruby SDK 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.                                           #
+#                                                                               #
+# Bluevia Ruby SDK 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 Bluevia Ruby SDK.  If not, see <http://www.gnu.org/licenses/>.     #
+#                                                                               #
+#                                                                               #
+#################################################################################

data/README

@@ -0,0 +1,172 @@
+
+ Bluevia client module definition
+
+ Introduction
+
+    Bluevia Ruby SDK allows you to use the BueVia public API from your Ruby
+    application using just a few lines of code.
+    You only need to download the SDK, include it into your LOAD_PATH directory
+    and leave magic work for you. If you download the gem this should be
+    automatically included in your gem local repository.
+
+    When you want to use as developer Bluevia public APIs,
+    first of all you need to get a commercial or testing API Key.
+ 
+    Ruby SDK wraps any request to BlueVia endpoint by using a generic object
+    BlueviaClient. This object uses the Component Pattern to fetch any service
+    required by the developer (oAuth, SMS or Directory).
+ 
+ Getting Started
+
+    Find below the gem dependencies required by Bluevia SDK:
+
+     - httpclient: used to create HTTP requests
+     - oauth: generic gem to launch the oAuth process
+     - nokogiri: used to parse XML responses (Advertising)
+     - json_pure: used to parse JSON responses
+
+    This snippet shows the easier way to create a new object with valid credentials
+    that identify the application:
+
+        require 'rubygems'
+        require 'bluevia'
+        include Bluevia
+
+        @bc = BlueviaClient.new(
+           { :consumer_key   => CONSUMER_KEY,
+             :consumer_secret=> CONSUMER_SECRET,
+             :uri            => "https://api.bluevia.com"
+           })
+
+ Endpoints
+
+    BlueVia has two endpoints, commercial and sandbox.
+    Commercial is linked to Telefonica network, and sandbox is used just to
+    verify application behavior.
+    The developer can change the endpoint just setting the desired behavior
+    in the client:
+ 
+       @bc.set_commercial
+       @bc.set_sandbox
+
+    Use the method @bc.commercial? to verify if the client is accessing either
+    commercial or sandbox endpoint.
+
+ Using Oauth
+ 
+    User authentication is launched using oAuth protocol, so user is not
+    required to use credentials in third party applications.
+    If you want to learn more about oAuth please check this URL: http://oauth.net.
+
+    When user wants to launch the oAuth process, once the Bluevia client object
+    has been created only the two lines below are required to retrieve 
+    a valid token for user:
+ 
+        @service = @bc.get_service(:oAuth)
+        token, secret, url = @service.get_request_token({:callback =>"http://foo.bar"})
+ 
+    The retrieved parameter token and secret should be used during the oAuth
+    process, and url is the endpoint where Bluevia shall authenticate the user.
+    In case of a Rails application, the lines below could be used:
+ 
+        token, token_secret, url = @service.get_request_token(
+                                "http://foo.bar/bluevia/get_access")
+        cookies[:token] = "#{token}|#{token_secret}"
+        redirect_to(url)
+ 
+    Both tokend and token_secret must be saved by the application provider
+    because oAuth process will require it later.
+
+    Once user is authenticated and she has authorized the application in 
+    BlueVia portal, she should be redirected to the URL used as parameter before.
+    Now it's time to fetch the valid token and token secret that shall identify
+    the new user during any call to BlueVia API. Lines below show an example using Rails:
+ 
+        def get_access
+            oauth_verifier = params[:oauth_verifier]
+            get_token_from_cookie
+            @bc = BlueviaClient.new(
+            { :consumer_key   => CONSUMER_KEY,
+             :consumer_secret=> CONSUMER_SECRET
+            })
+            @service = @bc.get_service(:oAuth)
+            @token, @token_secret = @service.get_access_token(@request_token, @request_secret, oauth_verifier)
+        end
+
+        private
+            def get_token_from_cookie
+                cookie_token = cookies[:token]
+                unless cookie_token.nil?
+                cookie_token = cookie_token.split("|")
+                if cookie_token.size != 2
+                    raise SyntaxError, "The cookie is not valid"
+                end
+                @request_token = cookie_token[0]
+                @request_secret = cookie_token[1]
+            end
+        end
+ 
+ Using BlueviaClient to launch requests
+ 
+    Most of requests when accessing Bluevia API are associated to a specific user,
+    so when a BlueviaClient object is created both user token and 
+    user token secret must be provided to identify user on behalf of
+    whom the application wants to access BlueVia APIs.
+ 
+        @bc = BlueviaClient.new(
+           { :consumer_key   => CONSUMER_KEY,
+             :consumer_secret=> CONSUMER_SECRET,
+             :token          => USER_TOKEN,
+             :token_secret   => TOKEN_SECRET,
+             :uri            => "https://api.bluevia.com"
+           })
+
+ Send a SMS
+
+    First of all, create the BlueviaClient object as shown before.
+
+    Any operation available in BlueviaClient object is associated to 
+    a specific service. Each service represents a specific enabler provided by Bluevia.
+
+    In case of SMS, these two lines are required to send a SMS on behalf of the user:
+ 
+        @service = @bc.get_service(:Sms)
+        info = @service.send_sms("11111", 
+                                 USER_TOKEN,
+                                 "Yet another SMS Text")
+ 
+ 
+
+ Request Directory Info
+ 
+    @service = @bc.get_service(:Directory)
+    response = @service.get_user_info(USER_TOKEN, Directory::USER_IDENTITIES)
+ 
+ Get Ad
+
+    With Advertising API a developer can fetch an ad to include in her application.
+
+    There are some required parameters:
+           - user_agent
+           - ad_request_id
+           - ad_space
+
+    And also optional parameters:
+           - ad_presentation
+           - ad_presentation_size
+           - keywords
+           - protection_policy
+
+    All parameters should be include in a single Hash object:
+
+    @service = @bc.get_service(:Advertising)
+
+    params = {
+       :user_agent => "Mozilla 5.0",
+       :ad_request_id => "a1x4zasg58",
+       :ad_space => "1200",
+       :keywords => "bar"
+    }
+
+    ad = @service.request(params)
+

data/lib/bluevia.rb

@@ -0,0 +1,13 @@
+#
+# BlueVia is a global iniciative of Telefonica delivered by Movistar and O2.
+# Please, check out www.bluevia.com and if you need more information
+# contact us at mailto:support@bluevia.com
+#
+
+require 'bluevia/bluevia_client'
+
+
+# Main Bluevia module definition
+module Bluevia
+  VERSION = "1.0"
+end

data/lib/bluevia/ad_response.rb

@@ -0,0 +1,35 @@
+
+#
+# BlueVia is a global iniciative of Telefonica delivered by Movistar and O2.
+# Please, check out www.bluevia.com and if you need more information
+# contact us at mailto:support@bluevia.com
+#
+
+module Bluevia
+  #
+  # Wrapper to fetch in an easy way the image or the text ad
+  #
+  class AdResponse < Array
+    #
+    # Fetch the image ad
+    #
+    def image
+      val = self.find_all{|item| item["type_name"].eql?("image")}
+      if val.instance_of?(Array) and val.length > 0
+        val = val[0]
+      end
+      val
+    end
+
+    #
+    # Fetch the text ad
+    #
+    def text
+      val = self.find_all{|item| item["type_name"].eql?("text")}
+      if val.instance_of?(Array) and val.length > 0
+        val = val[0]
+      end
+      val
+    end
+  end
+end

data/lib/bluevia/advertising.rb

@@ -0,0 +1,108 @@
+require 'bluevia/ad_response'
+
+#
+# BlueVia is a global iniciative of Telefonica delivered by Movistar and O2.
+# Please, check out www.bluevia.com and if you need more information
+# contact us at mailto:support@bluevia.com
+
+module Bluevia
+  #
+  # This class fetches information related to Advertising API.
+  #
+
+  class Advertising < BaseClient
+
+    # optional parameters in the request
+    OPTIONAL_PARAMS = [:ad_presentation, :ad_presentation_size, :keywords, :protection_policy]
+
+    # required parameters in the request
+    REQUIRED_PARAMS = [:user_agent, :ad_request_id, :ad_space]
+
+    VALID_PARAMS = OPTIONAL_PARAMS + REQUIRED_PARAMS
+
+    def initialize(params = nil)
+      super(params)
+    end
+
+    # Base Path for Advertising API
+    BASEPATH_API = "/Advertising"
+
+    #
+    # This method fetchs an Ad from the server.
+    # [*params*] Hash object that must include at least the REQUIRED_PARAMS and
+    # cero or more OPTIONAL_PARAMS
+    # i.e.
+    # 
+    # response = @service.request(
+    #      {:user_agent => "Mozilla 5.0",
+    #       :ad_request_id => "a1x4zasg58",
+    #       :ad_space => "1200",
+    #       :keywords => "bar"
+    #      })
+    #
+    def request(params)
+      Utils.check_attribute(params, "params cannot be null")
+      
+      REQUIRED_PARAMS.each { |param|
+        Utils.check_attribute(params[param], "#{param} cannot be null")
+      }
+
+      # delete any parameter that is neither optional nor mandatory
+      params.delete_if{|key,value| VALID_PARAMS.index(key).nil?}
+
+      # include in the request all the parameters
+      message = params.collect{|k,v| "#{k}=#{CGI::escape(v.to_s)}"}.join('&')
+
+      # this should be sent without content-Type because fails to validate signature
+      path = set_path("#{get_basepath}/simple/requests")
+      path = include_params(path, DEFAULT_PARAMS)
+      response = authorized_client.post(
+        path,
+        message,
+        {"Accept" => "application/json"})
+      
+      resp = handle_response(create_response(response)).body
+      
+      filter_response(resp)      
+    end
+
+    private
+
+    def filter_response(response)
+      if response.nil? or !response.instance_of?(Hash)
+        p "empty!!"
+      end
+            
+      return AdResponse.new if response.nil? or !response.instance_of?(Hash)
+
+      result = AdResponse.new
+      #begin
+        
+        id = response[:adResponse][:ad][:resource][:attributes][:ad_presentation]
+        resources = response[:adResponse][:ad][:resource][:creative_element]
+        item = Hash.new
+        if resources.instance_of?(Array)
+          resources.each{|resource|
+            result << assign_item(resource, id)
+          }
+        else
+          result << assign_item(resources, id)
+        end
+      #rescue
+      
+      #end
+      result
+    end
+
+    def assign_item(resource, id)
+      item = Hash.new
+      item["type_id"]     = id
+      item["type_name"]   = resource[:attributes][:type]
+      item["value"]       = resource[:attribute].instance_of?(Array) ? resource[:attribute][1] : resource[:attribute]
+      item["interaction"] = resource[:interaction][:attribute]
+
+      item
+    end
+
+  end
+end