vertigo 0.0.1.a → 0.0.1.b

data/.gitignore

@@ -22,3 +22,4 @@ tmtags
 *.gem
 .bundle
 pkg/*
+.yardoc/*

data/.travis.yml

@@ -0,0 +1,2 @@
+rvm:
+  - 1.8.7

data/Gemfile.lock

@@ -2,15 +2,33 @@ PATH
   remote: .
   specs:
     vertigo (0.0.1.a)
+      soap4r (~> 1.5.8)
 
 GEM
   remote: http://rubygems.org/
   specs:
+    diff-lcs (1.1.2)
+    fakeweb (1.3.0)
+    httpclient (2.2.1)
     rake (0.8.7)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    soap4r (1.5.8)
+      httpclient (>= 2.1.1)
+    yard (0.7.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  fakeweb (~> 1.3.0)
   rake (~> 0.8.7)
+  rspec (~> 2.6.0)
   vertigo!
+  yard (< 1.0.0)

data/{README.md → README.rdoc}

@@ -1,5 +1,4 @@
-Vertigo
-=======
+= Vertigo
 
 A simple Ruby wrapper around the VerticalResponse API ("VRAPI").
 
@@ -7,8 +6,9 @@ Vertigo makes working with the VerticalResponse SOAP API much more Ruby-like.  I
 
 Author: Benjamin Oakes <hello@benjaminoakes.com>, @benjaminoakes
 
-Installation
-------------
+http://travis-ci.org/benjaminoakes/vertigo.png ({More info}[http://travis-ci.org/benjaminoakes/vertigo])
+
+== Installation
 
 Simply add Vertigo to your Gemfile:
 
@@ -18,25 +18,32 @@ If you are unlucky enough not to be using Bundler:
 
     gem install vertigo
 
-Usage
------
+== Usage
 
 Basic usage example:
 
     require 'vertigo'
     
     session_duration_minutes = 4
-    client = Vertigo::Client.new('username', 'password', session_duration_minutes)
+    client = Vertigo::Client.new('username', 'password', :duration_minutes => 5)
 
     # Launch a campaign whose ID you already know:
     client.launch_email_campaign(:campaign_id => campaign_id)
 
-Contributing
-------------
+For more info, please see {Vertigo::Client} or {http://rubydoc.info/gems/vertigo the docs on RubyDoc.info}.
+
+== Compatibility
+
+* Written against the 2011.08.10 deploy of the VerticalResponse API "v1.0".  More information: http://developers.verticalresponse.com/api/soap/developers-reference/articles/verticalresponse-api-update-for-august-2011/
+
+== Contributing
+
+To set up your development environment, please run `bash dev-setup.sh`.
+
+When writing documentation:
 
-To set up your development environment, run `bash dev-setup.sh`.
+    bundle exec yard server --reload
 
-Thanks
-------
+== Thanks
 
 * Forrest Chang (@fkchang2000) for the name

data/Rakefile

@@ -1 +1,8 @@
-require 'bundler/gem_tasks'
+require 'rake'
+require 'rspec/core/rake_task'
+require 'bundler'
+
+task :default => :spec
+
+Bundler::GemHelper.install_tasks
+RSpec::Core::RakeTask.new(:spec)

data/TODO.rdoc

@@ -0,0 +1 @@
+* The "soap4r" gem does not play very well with Ruby 1.9.2.  Migrate to a new SOAP interface.

data/lib/vertigo.rb

@@ -1,5 +1,4 @@
-require "vertigo/version"
-
 module Vertigo
-  # Your code goes here...
+  autoload :Client, 'vertigo/client'
+  autoload :VERSION, 'vertigo/version'
 end

data/lib/vertigo/client.rb

@@ -0,0 +1,93 @@
+require 'soap/wsdlDriver'
+
+# Simple wrapper around the VerticalResponse SOAP API.
+#
+# = API Versioning
+#
+# As of 2011.08.15, VerticalResponse changes and remove API calls, but still call it API "v1.0" each time.  These mandatory API changes could break your code (although we have never experienced that personally).
+#
+# Inquiring about their versioning policy got this response:  "For a variety of internal reasons, this is still considered the 1.0 release of our API. We're currently exploring adding real versioning to our API to avoid these kinds of issues going forward."
+#
+# Because of this, Vertigo::Client regenerates the RPC driver when instantiated as the generated code for VRAPI.wsdl becomes stale over time.  Generating the driver incurs a startup cost, but it's minimal.
+#
+# @author Benjamin Oakes <hello@benjaminoakes.com>, @benjaminoakes
+class Vertigo::Client
+  DURATION_MINUTES = 4
+  WSDL_URL = 'https://api.verticalresponse.com/partner-wsdl/1.0/VRAPI.wsdl'  
+
+  # @param [String] username Account username
+  # @param [String] password Account password
+  # @param [Hash] opts Session options
+  # @option opts [Fixnum] :duration_minutes Duration of session in minutes
+  # @option opts [String] :wsdl_url Alternative WSDL URL
+  #
+  # @raise [SOAP::FaultError] when an API call fails
+  #
+  # @example Connect using session defaults
+  #     client = Vertigo::Client.new('you@yourcompany.com', 'your password')
+  #
+  # @example Connect using the specified session options
+  #     client = Vertigo::Client.new('you@yourcompany.com', 'your password', :duration_minutes => 5)
+  def initialize(username, password, opts = {})
+    session_duration_minutes = opts[:duration_minutes] || DURATION_MINUTES
+    wsdl_url = opts[:wsdl_url] || WSDL_URL
+
+    @api = SOAP::WSDLDriverFactory.new(wsdl_url).create_rpc_driver
+    @session_id = @api.login(
+      'username' => username.to_s,
+      'password' => password.to_s,
+      'session_duration_minutes' => session_duration_minutes
+    )
+  end
+
+  # This modification lets us write API calls in a more "Rubyish" manner.
+  #
+  # @note camelCase method names are still supported.
+  #
+  # @raise [ArgumentError] when too many arguments or unsupported arguments
+  # @raise [NoMethodError] when the API call is not defined
+  #
+  # @example Unlaunching an email campaign
+  #     client.unlaunch_email_campaign(:campaign_id => 1)
+  #     # Without Vertigo::Client, it would be:
+  #     vrapi.unlaunchEmailCampaign('session_id' => session_id, 'campaign_id' => 1)
+  def method_missing(name, *args, &block)
+    options = args[0]
+    vr_name = camelize_meth(name).intern
+
+    if args.length > 1
+      raise ArgumentError, 'Unexpected number of arguments (not 0 or 1)'
+    elsif options && !options.respond_to?(:keys)
+      raise ArgumentError, "options does not respond to :keys (options.class: #{options.class}, options: #{options.inspect})"
+    end
+
+    if @api.respond_to?(vr_name)
+      vr_args = options ? stringify_keys(options) : {}
+      @api.send(vr_name, {'session_id' => @session_id}.merge(vr_args))
+    else
+      raise NoMethodError, "Undefined VerticalResponse API call: #{vr_name.inspect}"
+    end
+  end
+
+private
+
+  # Camelize a method name
+  # 
+  # @param [String, Symbol] name
+  def camelize_meth(name)
+    name.to_s.gsub(/_([a-z])/) { $1.upcase }
+  end
+
+  # Recursively stringify keys of Hashes and members of Arrays
+  #
+  # @param [Hash, Array, Object] original
+  def stringify_keys(original)
+    if original.respond_to?(:keys)
+      Hash[original.map { |key, val| [key.to_s, stringify_keys(val)] }]
+    elsif original.kind_of?(Array)
+      original.map { |val| stringify_keys(val) }
+    else
+      original
+    end
+  end
+end

data/lib/vertigo/version.rb

@@ -1,3 +1,3 @@
 module Vertigo
-  VERSION = '0.0.1.a'
+  VERSION = '0.0.1.b'
 end

data/spec/lib/vertigo/client_spec.rb

@@ -0,0 +1,117 @@
+require 'spec_helper'
+
+describe Vertigo::Client do
+  before :each do
+    @username = 'you@yourcompany.com'
+    @password = 'secret'
+    @api = mock('API', :login => 'mock session ID')
+    @api.stub!(:unlaunchEmailCampaign)
+    @api.stub!(:enumerateEmailCampaigns)
+    @factory = mock('WSDLDriverFactory', :create_rpc_driver => @api)
+  end
+
+  it 'should create a RPC driver with the default WSDL' do
+    SOAP::WSDLDriverFactory.should_receive(:new).with(Vertigo::Client::WSDL_URL).and_return(@factory)
+    Vertigo::Client.new(@username, @password)
+  end
+
+  it 'should create a RPC driver with the specified WSDL' do
+    url = 'https://api.verticalresponse.com/partner-wsdl/1.1/VRAPI.wsdl'  
+    SOAP::WSDLDriverFactory.should_receive(:new).with(url).and_return(@factory)
+    Vertigo::Client.new(@username, @password, :wsdl_url => url)
+  end
+
+  context 'with default WSDL' do
+    before :each do
+      SOAP::WSDLDriverFactory.stub!(:new).and_return(@factory)
+    end
+
+    it 'should log in with the given credentials' do
+      @api.should_receive(:login, {
+        'username' => @username,
+        'password' => @username,
+        'session_duration_minutes' => Vertigo::Client::DURATION_MINUTES
+      })
+
+      Vertigo::Client.new(@username, @password)
+    end
+
+    it 'should log in with the given credentials and session duration' do
+      @api.should_receive(:login, {
+        'username' => @username,
+        'password' => @username,
+        'session_duration_minutes' => 5
+      })
+
+      Vertigo::Client.new(@username, @password, :duration_minutes => 5)
+    end
+  end
+
+  context 'with client' do
+    before :each do
+      SOAP::WSDLDriverFactory.stub!(:new).and_return(@factory)
+
+      @client = Vertigo::Client.new(@username, @password)
+      # White box test
+      @session_id = @client.instance_eval { @session_id }
+    end
+
+    it 'should allow Rubyish method calls' do
+      @api.should_receive(:unlaunchEmailCampaign).with('session_id' => @session_id, 'campaign_id' => 1)
+      @client.unlaunch_email_campaign(:campaign_id => 1)
+    end
+
+    it 'should allow Rubyish method calls with no arguments' do
+      @api.should_receive(:enumerateEmailCampaigns).with('session_id' => @session_id)
+      @client.enumerate_email_campaigns
+    end
+
+    it 'should still allow camelcase method calls' do
+      @api.should_receive(:unlaunchEmailCampaign).with('session_id' => @session_id, 'campaign_id' => 1)
+      @client.unlaunchEmailCampaign(:campaign_id => 1)
+    end
+
+    it 'should raise an error if given two arguments' do
+      lambda { @client.unlaunch_email_campaign(2, :campaign_id => 1) }.should raise_error(ArgumentError)
+    end
+
+    it 'should raise an error if called with an undefined VerticalResponse API call' do
+      lambda { @client.some_random_method(:campaign_id => 1) }.should raise_error(NoMethodError)
+    end
+
+    it 'should raise an error if given an unsupported argument' do
+      lambda { @client.unlaunch_email_campaign(2) }.should raise_error(ArgumentError)
+    end
+
+    it 'should' do
+      @api.should_receive(:createEmailCampaign).with(
+        'session_id' => @session_id,
+        'email_campaign' => {
+          'name' => 'Campaign Name',
+          'type' => 'freeform',
+          'from_label' => 'from@example.com',
+          'support_email' => 'support@example.com',
+          'send_friend' => false,
+          'contents' => [
+            { 'type' => 'freeform_html', 'copy' => 'body' },
+            { 'type' => 'freeform_text', 'copy' => 'body' },
+            { 'type' => 'subject', 'copy' => 'subject' },
+          ]
+        }
+      )
+
+      @client.create_email_campaign(:email_campaign => {
+        :name => 'Campaign Name',
+        :type => 'freeform',
+        :from_label => 'from@example.com',
+        :support_email => 'support@example.com',
+        :send_friend => false,
+        :contents => [
+          { :type => 'freeform_html', :copy => 'body' },
+          { :type => 'freeform_text', :copy => 'body' },
+          { :type => 'subject', :copy => 'subject' },
+        ]
+      })
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'fakeweb'
+require 'rspec'
+
+require 'vertigo'
+
+RSpec.configure do |c|
+  c.mock_with :rspec
+end
+
+FakeWeb.allow_net_connect = false

data/vertigo.gemspec

@@ -13,7 +13,12 @@ Gem::Specification.new do |s|
 
   s.rubyforge_project = "vertigo"
   
+  s.add_dependency('soap4r', '~> 1.5.8')
+
+  s.add_development_dependency('fakeweb', '~> 1.3.0')
   s.add_development_dependency('rake', '~> 0.8.7')
+  s.add_development_dependency('rspec', '~> 2.6.0')
+  s.add_development_dependency('yard', '< 1.0.0')
 
   s.files         = `git ls-files`.split("\n")
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification 
 name: vertigo
 version: !ruby/object:Gem::Version 
-  hash: 46
+  hash: 47
   prerelease: 6
   segments: 
   - 0
   - 0
   - 1
-  - a
-  version: 0.0.1.a
+  - b
+  version: 0.0.1.b
 platform: ruby
 authors: 
 - Benjamin Oakes
@@ -16,13 +16,45 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-15 00:00:00 -04:00
+date: 2011-08-16 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rake
+  name: soap4r
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 1
+        - 5
+        - 8
+        version: 1.5.8
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: fakeweb
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -34,7 +66,39 @@ dependencies:
         - 7
         version: 0.8.7
   type: :development
-  version_requirements: *id001
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 2
+        - 6
+        - 0
+        version: 2.6.0
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - <
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 1
+        - 0
+        - 0
+        version: 1.0.0
+  type: :development
+  version_requirements: *id005
 description: Vertigo makes working with VerticalResponse's SOAP API much more Ruby-like.  It manages your session_id, as well as letting you write methods as launch_email_campaign rather than launchEmailCampaign, and use symbols as keys rather than strings.
 email: 
 - boakes@hedgeye.com
@@ -47,13 +111,18 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - .rvmrc
+- .travis.yml
 - Gemfile
 - Gemfile.lock
-- README.md
+- README.rdoc
 - Rakefile
+- TODO.rdoc
 - dev-setup.sh
 - lib/vertigo.rb
+- lib/vertigo/client.rb
 - lib/vertigo/version.rb
+- spec/lib/vertigo/client_spec.rb
+- spec/spec_helper.rb
 - vertigo.gemspec
 has_rdoc: true
 homepage: ""
@@ -91,5 +160,6 @@ rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: A simple Ruby wrapper around the VerticalResponse API ("VRAPI").
-test_files: []
-
+test_files: 
+- spec/lib/vertigo/client_spec.rb
+- spec/spec_helper.rb