cloudsponge 0.9.3

data/HISTORY

@@ -0,0 +1,4 @@
+=== 0.9.2 / 2010-04-20
+
+* Created Gem version of basic library functionality
+

data/Manifest.txt

@@ -0,0 +1,15 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/cloudsponge.rb
+lib/cloudsponge/contact.rb
+lib/cloudsponge/contact_importer.rb
+lib/cloudsponge/cs_exception.rb
+lib/cloudsponge/event.rb
+lib/cloudsponge/utility.rb
+test/test_contact.rb
+test/test_contact_importer.rb
+test/test_cs_exception.rb
+test/test_utility.rb
+TODO

data/README

@@ -0,0 +1,70 @@
+= cs_import
+
+http://www.cloudsponge.com
+
+== DESCRIPTION:
+
+Spread the word with an email invite. Import contacts from Yahoo, Hotmail, MSN, Gmail, AOL, Outlook and Mac Address Book.
+
+== FEATURES/PROBLEMS:
+
+=== Problem
+Websites looking to grow their customer base usually turn to traditional, paid methods of advertising like search engine keywords, media buys, and generic email lists. Though these methods can be effective at times, they are no match for the testimonial power your very own customers can bring. By encouraging your customers to promote your site to their family and friends, you have an inexpensive advertising channel to acquire customers. If one customer refers their friends, and their friends refer their friends, and so on, and so on, you now have a viral site!
+
+=== Solution
+  CloudSponge.com is THE tool you need to go viral! Here's how it works:
+  * Ask your customers to invite all their friends and family to your site.
+  * Use CloudSponge.com to pull your customer's contact list with their permission.
+  * Send an email invite to all the contacts provided by CloudSponge.com.
+  * Sit back and watch your customer base grow virally!
+
+== SYNOPSIS:
+
+  Usage:
+  contacts = nil
+  importer = Cloudsponge::ContactImporter.new(DOMAIN_KEY, DOMAIN_PASSWORD)
+  resp = importer.begin_import('YAHOO')
+  puts "Navigate to #{resp[:consent_url]} and complete the authentication process."
+  loop do
+    events = importer.get_events
+    break unless events.select{ |e| e.is_error? }.empty?
+    unless events.select{ |e| e.is_complete? }.empty?
+      contacts = importer.get_contacts
+      break
+    end
+  end
+
+== REQUIREMENTS:
+
+JSON decoding package, currently supported are ActiveSupport::JSON and the JSON gem.
+  Neither of these are required, but if you don't have either on your system, a runtime 
+  error will be generated.
+
+== INSTALL:
+
+sudo gem install cloudsponge
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Cloud Copy, Inc.
+
+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/Rakefile

@@ -0,0 +1,44 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+require 'lib/cloudsponge'
+
+PKG_FILES = FileList["**/*"].exclude(/CVS|pkg|tmp|coverage|Makefile|\.nfs\./)
+
+spec = Gem::Specification.new do |s|
+  s.name = 'cloudsponge'
+  s.version = Cloudsponge::VERSION
+  s.author = "Graeme Rouse"
+  s.email = "graeme@cloudsponge.com"
+  s.homepage = "http://www.cloudsponge.com"
+  s.platform  = Gem::Platform::RUBY
+  s.summary = "A library wrapper for Cloudsponge.com's API"
+  s.description = <<-EOF
+    Usage:
+      contacts = nil
+      importer = Cloudsponge::ContactImporter.new(DOMAIN_KEY, DOMAIN_PASSWORD)
+      importer.begin_import('YAHOO')
+      loop do
+        events = importer.get_events
+        break unless events.select{ |e| e.is_error? }.empty?
+        unless events.select{ |e| e.is_completed? }.empty?
+          contacts = importer.get_contacts
+          break
+        end
+      end
+  EOF
+  
+  #s.files = FileList["{test,lib}/**/*"].exclude("rdoc").to_a
+  s.files = PKG_FILES
+#  s.files = PKG_FILES
+  s.require_path = "lib"
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "HISTORY", "TODO"]
+end
+
+
+Rake::GemPackageTask.new(spec) do |pkg| 
+  pkg.need_tar = true 
+end

data/TODO

@@ -0,0 +1,3 @@
+* Write comprehensive tests
+* Add interactive command line example program
+* Add xml decoding in no JSON lib is available.

data/lib/cloudsponge.rb

@@ -0,0 +1,9 @@
+require File.expand_path(File.dirname(__FILE__) + '/cloudsponge/contact_importer')
+require File.expand_path(File.dirname(__FILE__) + '/cloudsponge/contact')
+require File.expand_path(File.dirname(__FILE__) + '/cloudsponge/event')
+require File.expand_path(File.dirname(__FILE__) + '/cloudsponge/cs_exception')
+require File.expand_path(File.dirname(__FILE__) + '/cloudsponge/utility')
+
+module Cloudsponge
+  VERSION = '0.9.3'
+end

data/lib/cloudsponge/contact.rb

@@ -0,0 +1,40 @@
+module Cloudsponge
+  
+  class Contact
+    attr_accessor :first_name, :last_name, :emails, :phones
+
+    def self.from_array(list)
+      list.map { |contact_data| Contact.new(contact_data) }.compact
+    end
+
+    def initialize(contact_data)
+      # get the basic data
+      self.first_name = contact_data['first_name']
+      self.last_name = contact_data['last_name']
+      # get the phone numbers
+      self.phones = []
+      contact_data['phone'] && contact_data['phone'].each do |phone|
+        self.add_array_value(self.phones, phone['number'], phone['type'])
+      end
+      self.emails = []
+      contact_data['email'] && contact_data['email'].each do |email|
+        self.add_array_value(self.emails, email['address'], email['type'])
+      end
+      self
+    end
+
+    def name
+      "#{self.first_name} #{self.last_name}"
+    end
+    def email
+      self.emails && self.emails.first && self.emails.first[:value]
+    end
+    def phone
+      self.phones && self.phones.first && self.phones.first[:value]
+    end
+    def add_array_value(collection, value, type = nil)
+      collection << {:value => value, :type => type}
+    end
+  end
+
+end

data/lib/cloudsponge/contact_importer.rb

@@ -0,0 +1,176 @@
+# CloudSponge.com Ruby Library
+# http://www.cloudsponge.com
+# Copyright (c) 2010 Cloud Copy, Inc.
+# Licensed under the MIT license: http://www.opensource.org/licenses/mit-license.php
+# 
+# Written by Graeme Rouse
+# graeme@cloudsponge.com
+
+module Cloudsponge
+  # Constants
+  URL_BASE      = "https://api.cloudsponge.com/"
+  BEGIN_PATH    = "begin_import/"
+  CONSENT_PATH  = "user_consent/"
+  IMPORT_PATH   = "import/"
+  APPLET_PATH   = "desktop_applet/"
+  EVENTS_PATH   = "events/"
+  CONTACTS_PATH = "contacts/"
+
+  class ContactImporter
+    attr_accessor :key, :password, :import_id
+
+    def initialize(key = nil, password = nil)
+      @key, @password = [key, password]
+    end
+
+    # guesses the most appropriate invocation for begin_import_xxx()
+    #   returns an array of possible objects
+    #    [
+    #      :import_id => <import_id>,
+    #      :consent_url => nil | <consent_url>,
+    #      :applet_tag  => nil | <applet_tag>
+    #    ]
+    def begin_import(source_name, username = nil, password = nil, user_id = '', redirect_url = nil)
+      id = nil
+      consent_url = nil
+      applet_tag = nil
+
+      # look at the given service and decide how which begin function to invoke.
+      unless username.nil? || username.empty?
+        resp = begin_import_username_password(source_name, username, password, user_id)
+      else
+        unless (source_name =~ /OUTLOOK/i || source_name =~ /ADDRESSBOOK/i).nil?
+          resp = begin_import_applet(source_name, user_id)
+          applet_tag = create_applet_tag(resp['id'], resp['url'])
+        else
+          resp = begin_import_consent(source_name, user_id, redirect_url)
+          consent_url = resp['url']
+        end
+      end
+
+      @import_id = resp['import_id']
+
+      {:import_id => resp['import_id'], :consent_url => consent_url, :applet_tag => applet_tag}
+    end
+
+    # returns an array of Cloudsponge::Events with any new event or nil if no new events are available
+    def get_events(import_id = nil)
+      import_id ||= @import_id
+      
+      # call to CloudSponge.com for the latest event status and return it
+      # create the appropriate url to fetch the contacts
+      full_url = generate_poll_url(EVENTS_PATH, import_id)
+
+      # get the response from the server and decode it
+      resp = Utility.get_and_decode_response(full_url)
+      # interpret the result
+      Event.from_array(resp['events'])
+    end
+
+    # call to CloudSponge.com for the contacts,
+    # returns nil (not ready)
+    # or [an array of Contacts, the contacts_owner record]
+    def get_contacts(import_id = nil)
+      import_id ||= @import_id
+      contacts = nil
+      if resp = get_contacts_raw(import_id)
+        # decode the contacts for consumption
+        contacts = Contact.from_array(resp['contacts'])
+        contacts_owner = Contact.new(resp['contacts_owner']) rescue nil
+      end
+      [contacts, contacts_owner]
+    end
+
+    # call to CloudSponge.com for the contacts,
+    # returns nil (not ready)
+    # or a hashmap of contact data
+    def get_contacts_raw(import_id)
+      resp = nil
+
+      # get the response from the server and decode it
+      begin
+        resp = Utility.get_and_decode_response(generate_poll_url(CONTACTS_PATH, import_id))
+      rescue CsException => e
+        raise e unless e.code == 404
+      end
+
+      resp
+    end
+  
+  private
+  
+    # invokes the begin import action for the user consent process.
+    #   returns the URL of the consent page that the user must use to sign in and grant consent
+    #   throws an exception if an invalid service is invoked.
+    def begin_import_consent(source_name, user_id = nil, redirect_url = nil)
+      # we need to pass in all params to the call
+      params = {:service => source_name, :user_id => user_id, :redirect_url => redirect_url}.reject{ |k,v| v.nil? || v.empty? }
+
+      # get and decode the response into an associated array
+      # Throws an exception if there was a problem at the server
+      Utility.post_and_decode_response(full_url(CONSENT_PATH), authenticated_params(params))
+    end
+
+    # invokes the begin import action for the desktop applet import process.
+    # returns the URL of the applet that should be displayed to the user within the appropriate applet tag
+    # throws an exception if an invalid service is invoked.
+    def begin_import_applet(source_name, user_id = nil)
+      # we need to pass in all params to the call
+      params = {:service => source_name, :user_id => user_id}
+
+      # get and decode the response into an associated array
+      # Throws an exception if there was a problem at the server
+      Utility.post_and_decode_response(full_url(APPLET_PATH), authenticated_params(params))
+    end
+
+    # invokes the begin import action for the desktop applet import process.
+    # returns the URL of the applet that should be displayed to the user within the appropriate applet tag
+    # throws an exception if an invalid service is invoked.
+    def begin_import_username_password(source_name, username, password, user_id)
+      # we need to pass in all params to the call
+      params = {:service => source_name, :user_id => user_id, :username => username, :password => password}
+
+      # get and decode the response into an associated array
+      # Throws an exception if there was a problem at the server
+      Utility.post_and_decode_response(full_url(IMPORT_PATH), authenticated_params(params))
+    end
+    
+    def full_url(path)
+      "#{URL_BASE}#{BEGIN_PATH}#{path}"
+    end
+
+    def authenticated_params(params = {})
+      # append domain_key, domain_password to params and serialze into a query string
+      params.merge({:domain_key => self.key, :domain_password => self.password})
+    end
+
+    def authenticated_query(params = {})
+      # append domain_key, domain_password to params and serialze into a query string
+      Utility.object_to_query(authenticated_params(params))
+    end
+
+    def create_applet_tag(id, url)
+      <<-EOS
+  <APPLET archive="#{url}" code="ContactsApplet" id="Contact_Importer" width="0" height="0">
+    <PARAM name="cookieValue" value="document.cookie"/>
+    <PARAM name="importId" value="#{id}"/>
+    Your browser does not support Java which is required for this utility to operate correctly.
+  </APPLET>
+  EOS
+    end
+
+    def generate_poll_url(path, import_id)
+      # get the query_string with authentication params and assemble the full url
+      "#{URL_BASE}#{path}#{import_id}?#{authenticated_query}"
+    end
+  
+  end
+end
+
+
+
+
+
+
+  
+

data/lib/cloudsponge/cs_exception.rb

@@ -0,0 +1,9 @@
+module Cloudsponge
+  class CsException < StandardError 
+    attr :code
+    def initialize(message, code)
+      super(message)
+      @code = code
+    end
+  end
+end

data/lib/cloudsponge/event.rb

@@ -0,0 +1,33 @@
+module Cloudsponge
+  EVENT_TYPES = %w{ INITIALIZING GATHERING SUBMITTING COMPLETE ERROR}
+  EVENT_STATUSES = %w{ PENDING INPROGRESS COMPLETED ERROR }
+  
+  class Event
+    attr_accessor :event_type, :status, :value, :description
+
+    def self.from_array(list)
+      list.map { |event_data| Event.new(event_data) }.compact
+    end
+
+    def initialize(event_data)
+      # is it an error?
+      
+      # get the basic data
+      self.event_type = event_data['event_type']
+      self.status = event_data['status']
+      self.value = event_data['value']
+      self.description = event_data['description']
+      self
+    end
+    
+    def is_error?
+      self.event_type == 'ERROR'
+    end
+
+    def is_complete?
+      self.event_type == 'COMPLETE' && self.status == 'COMPLETED'
+    end
+
+  end
+
+end

data/lib/cloudsponge/utility.rb

@@ -0,0 +1,82 @@
+module Cloudsponge
+  
+  require "net/http"
+  require "net/https"
+  require "uri"
+
+  begin
+    require 'json'
+  rescue
+  end
+  
+  class Utility
+    
+    def self.object_to_query(object)
+      return object unless object.is_a? Hash
+      object.map{ |k,v| "#{URI.encode(k.to_s)}=#{URI.encode(v.to_s)}" }.join('&')
+    end
+    
+    def self.post_and_decode_response(url, params)
+      # post the response
+      response = post_url(url, params)
+      if response.code_type == Net::HTTPOK
+        # decode the response into an asscoiative array
+        resp = decode_response(response.body, 'json')
+        raise CsException.new(resp['error']['message'], response['code']) if resp['error']
+      else
+        raise CsException.new(response.body, response.code)
+      end
+      resp
+    end
+
+    def self.get_and_decode_response(full_url)
+      # get the response
+      response = get_url(full_url)
+
+      if response.code_type == Net::HTTPOK
+        # decode the response into an asscoiative array
+        resp = decode_response(response.body, 'json')
+        raise CsException.new(resp['error']['message'], response['code']) if resp['error']
+      else
+        raise CsException.new(response.body, response.code)
+      end
+      resp
+    end
+
+    def self.decode_response(response, format = 'json')
+      # TODO: account for systems that use a different JSON parser. Look for json gem...
+      # TODO: implement alternate formats: XML
+      object = {'error' => {'message' => 'failed to parse data.', 'code' => 1}}
+      begin
+        object = ActiveSupport::JSON.decode(response)
+      rescue
+        begin 
+          object = JSON.parse(response)
+        rescue
+        end
+      end
+      object
+    end
+
+    def self.get_url(url)
+      url = URI.parse(url)
+      open_http(url).get("#{url.path}?#{url.query}")
+    end
+
+    def self.post_url(url, params)
+      url = URI.parse(url)
+      open_http(url).post("#{url.path}","#{object_to_query(params)}")
+    end
+
+    def self.open_http(url)
+      http = Net::HTTP.new(url.host, url.port)
+      # @csimport_http.read_timeout = @timeout || 30
+      if url.port == 443
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      http.start unless http.started?
+      http
+    end
+  end
+end

data/test/test_contact.rb

@@ -0,0 +1,22 @@
+require "test/unit"
+require "cloudsponge"
+
+class TestContact < Test::Unit::TestCase
+  def test_new_from_data
+    data = {'first_name' => 'John', 'last_name' => 'Smith', 'email' => nil, 'phone' => nil}
+    assert contact = Cloudsponge::Contact.new(data)
+    assert_equal data['first_name'], contact.first_name
+    assert_equal data['last_name'], contact.last_name
+    assert_equal "#{data['first_name']} #{data['last_name']}", contact.name
+    assert_equal nil, contact.email
+    assert_equal nil, contact.phone
+
+    data = {'first_name' => 'John', 'last_name' => 'Smith', 'email' => [{'address' => 'joe@example.com'}], 'phone' => [{'number' => '555-1234'}]}
+    assert contact = Cloudsponge::Contact.new(data)
+    assert_equal data['first_name'], contact.first_name
+    assert_equal data['last_name'], contact.last_name
+    assert_equal "#{data['first_name']} #{data['last_name']}", contact.name
+    assert_equal 'joe@example.com', contact.email
+    assert_equal '555-1234', contact.phone
+  end
+end

data/test/test_contact_importer.rb

@@ -0,0 +1,42 @@
+require "test/unit"
+require File.dirname(__FILE__) + "/../lib/cloudsponge"
+
+class TestContactImporter < Test::Unit::TestCase
+  def test_version_exists
+    assert Cloudsponge::VERSION
+  end
+  
+  DOMAIN_KEY = "Your Domain Key"
+  DOMAIN_PASSWORD = "Your Domain Password"
+  
+  def test_u_p_import
+    contacts = nil
+    importer = Cloudsponge::ContactImporter.new(DOMAIN_KEY, DOMAIN_PASSWORD)
+    importer.begin_import('AOL', 'username', 'password')
+    loop do
+      events = importer.get_events
+      break unless events.select{ |e| e.is_error? }.empty?
+      unless events.select{ |e| e.is_complete? }.empty?
+        contacts = importer.get_contacts
+        break
+      end
+    end
+    assert contacts
+  end
+
+  def test_auth_import
+    contacts = nil
+    importer = Cloudsponge::ContactImporter.new(DOMAIN_KEY, DOMAIN_PASSWORD)
+    resp = importer.begin_import('YAHOO')
+    puts "Navigate to #{resp[:consent_url]} and complete the authentication process."
+    loop do
+      events = importer.get_events
+      break unless events.select{ |e| e.is_error? }.empty?
+      unless events.select{ |e| e.is_complete? }.empty?
+        contacts = importer.get_contacts
+        break
+      end
+    end
+    assert contacts
+  end
+end

data/test/test_cs_exception.rb

@@ -0,0 +1,7 @@
+require "test/unit"
+require "cloudsponge"
+
+class TestCsException < Test::Unit::TestCase
+  def test_version_exists
+  end
+end

data/test/test_utility.rb

@@ -0,0 +1,11 @@
+
+require "test/unit"
+require "../lib/cloudsponge"
+
+class TestUtility < Test::Unit::TestCase
+  def test_decode_response
+    require "json"
+    object = {'key1' => 'value1', 'key2' => 'value2', 'integer_key' => 5}
+    assert_equal object, Cloudsponge::Utility.decode_response(JSON.generate(object))
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: cloudsponge
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 9
+  - 3
+  version: 0.9.3
+platform: ruby
+authors: 
+- Graeme Rouse
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-20 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: "    Usage:\n      contacts = nil\n      importer = Cloudsponge::ContactImporter.new(DOMAIN_KEY, DOMAIN_PASSWORD)\n      importer.begin_import('YAHOO')\n      loop do\n        events = importer.get_events\n        break unless events.select{ |e| e.is_error? }.empty?\n        unless events.select{ |e| e.is_completed? }.empty?\n          contacts = importer.get_contacts\n          break\n        end\n      end\n"
+email: graeme@cloudsponge.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- HISTORY
+- TODO
+files: 
+- HISTORY
+- lib/cloudsponge/contact.rb
+- lib/cloudsponge/contact_importer.rb
+- lib/cloudsponge/cs_exception.rb
+- lib/cloudsponge/event.rb
+- lib/cloudsponge/utility.rb
+- lib/cloudsponge.rb
+- Manifest.txt
+- Rakefile
+- README
+- test/test_contact.rb
+- test/test_contact_importer.rb
+- test/test_cs_exception.rb
+- test/test_utility.rb
+- TODO
+has_rdoc: true
+homepage: http://www.cloudsponge.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A library wrapper for Cloudsponge.com's API
+test_files: []
+