campaigning 0.15.0

data/.bnsignore

@@ -0,0 +1,16 @@
+# The list of files that should be ignored by Mr Bones.
+# Lines that start with '#' are comments.
+#
+# A .gitignore file can be used instead by setting it as the ignore
+# file in your Rakefile:
+#
+#   PROJ.ignore_file = '.gitignore'
+#
+# For a project with a C extension, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+# *.[oa]
+# *~
+announcement.txt
+coverage
+doc
+pkg

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Marcelo Menezes
+
+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.rdoc

@@ -0,0 +1,65 @@
+= Campaigning
+
+This is a Ruby wrapper around CampaignMonitor API(www.campaignmonitor.com/api) using SOAP.
+
+
+== Pre-requisites
+An account with Campaign Monitor and the API Key (www.campaignmonitor.com).
+
+
+== Resources
+
+=== Dependencies
+
+This gem requires the following gems:
+ 
+ Soap4r (1.5.8)
+ 
+ Jeweler (http://technicalpickles.com/posts/craft-the-perfect-gem-with-jeweler)
+
+=== Installing
+
+  sudo gem install gnumarcelo-campaigning -s http://gems.github.com
+
+
+=== Configuring your API key
+  require 'campaigning'
+  CAMPAIGN_MONITOR_API_KEY = '_put_here_your_api_key_'
+
+
+== Usage
+
+This gem provides a set of classes to access all available information on Campaign Monitor.
+
+These are the list of classes:
+
+  Campaigning, Campaigning::Client, Campaigning::Campaign, Campaigning::List and Campaigning::Subscriber
+
+The examples below assumes you have set *CAMPAIGN_MONITOR_API_KEY* constant with your Campaign monitor API.
+
+Sample use of the Client class:
+
+  #Here is how to get a list of all clients...
+  clients = Campaigning::Client.get_all_clients
+
+
+  #Here is how to create a brand new subscriber list for an Client
+  client = Campaigning::Client.find_by_name("Client One Company")
+  list = Campaigning::List.create!(
+    :clientID => client.clientID,
+    :title => "List of people from Brazil",
+    :confirmOptIn => false
+  )
+
+For further examples please check at the *sample* directory.
+
+
+== What if I found a BUG?
+
+If you found a bug in the Campaigning wrapper, it's easy to report it on the like below:  
+  http://github.com/gnumarcelo/campaigning/issues
+
+
+== Copyright
+
+Copyright (c) 2009 Marcelo Menezes. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,59 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "campaigning"
+    gem.summary = %Q{TODO}
+    gem.email = "gnumarcelo@gmail.com"
+    gem.homepage = "http://github.com/gnumarcelo/campaigning"
+    gem.authors = ["Marcelo Menezes"]
+    gem.add_dependency('soap4r', '~> 1.5.0')
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "campaigning #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.exclude('lib/campaigning/soap/generated/*.rb')
+  rdoc.options << "--inline-source"
+end
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 15
+:patch: 0

data/campaigning.gemspec

@@ -0,0 +1,77 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{campaigning}
+  s.version = "0.15.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Marcelo Menezes"]
+  s.date = %q{2009-11-30}
+  s.email = %q{gnumarcelo@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".bnsignore",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION.yml",
+     "campaigning.gemspec",
+     "lib/campaigning.rb",
+     "lib/campaigning/campaign.rb",
+     "lib/campaigning/campaigning.rb",
+     "lib/campaigning/client.rb",
+     "lib/campaigning/list.rb",
+     "lib/campaigning/module_mixin.rb",
+     "lib/campaigning/soap/generated/default.rb",
+     "lib/campaigning/soap/generated/defaultDriver.rb",
+     "lib/campaigning/soap/generated/defaultMappingRegistry.rb",
+     "lib/campaigning/subscriber.rb",
+     "lib/campaigning/template.rb",
+     "sample/campaign_sample.rb",
+     "sample/campaigning_sample.rb",
+     "sample/client_sample.rb",
+     "sample/list_sample.rb",
+     "sample/subscriber_sample.rb",
+     "test/campaign_test.rb",
+     "test/campaigning_test.rb",
+     "test/client_test.rb",
+     "test/list_test.rb",
+     "test/subscriber_test.rb",
+     "test/template_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/gnumarcelo/campaigning}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Interfaces with the campaign monitor api}
+  s.test_files = [
+    "test/campaign_test.rb",
+     "test/campaigning_test.rb",
+     "test/client_test.rb",
+     "test/list_test.rb",
+     "test/subscriber_test.rb",
+     "test/template_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<soap4r>, ["~> 1.5.0"])
+    else
+      s.add_dependency(%q<soap4r>, ["~> 1.5.0"])
+    end
+  else
+    s.add_dependency(%q<soap4r>, ["~> 1.5.0"])
+  end
+end

data/lib/campaigning.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + '/campaigning/campaigning'

data/lib/campaigning/campaign.rb

@@ -0,0 +1,218 @@
+# Campaign is defined in soap/default.rb which is automatically generated.
+# In this file we add additional methods to the Campaign class.
+require File.expand_path(File.dirname(__FILE__)) + '/module_mixin'
+
+
+module Campaigning
+  class Campaign
+    include ModuleMixin   
+    attr_accessor :campaignID
+    attr_accessor :subject
+    attr_accessor :name
+    attr_accessor :sentDate
+    attr_accessor :totalRecipients
+    
+    def initialize(campaignID = nil, subject = nil, name = nil, sentDate = nil, totalRecipients = nil, opts={})
+      @apiKey     = opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY
+      @campaignID = campaignID
+      @subject    = subject
+      @name       = name
+      @sentDate   = sentDate
+      @totalRecipients = totalRecipients
+    end
+    
+    #Creates a campaign for an existing client. This campaign will be imported and ready to send to the subscribers in
+    #the specified lists and segments.
+    #The campaign must have both HTML and plain text content, imported from the internet. Styling for the HTML content
+    #will be automatically brought inline.
+    #
+    #Available _params_ argument are:
+    #   * :clientID - The ID of the Client you want to create a campaign
+    #   * :campaignName - The name of the new campaign. This must be unique across all draft campaigns for the client.
+    #   * :campaignSubject - The subject of the new campaign.
+    #   * :fromName - The name to appear in the From field in the recipients email client when they receive the new campaign.
+    #   * :fromEmail - The email address that the new campaign will come from.
+    #   * :replyTo - The email address that any replies to the new campaign will be sent to.
+    #   * :htmlUrl - The URL of the HTML content for the new campaign. If no unsubscribe link is found then one will be added automatically. Styling in
+    #                the campaign will be automatically brought inline. If your URL has querystring values, you will need to encode them.
+    #   * :textUrl - The URL of the Text content for the new campaign. If no unsubscribe link is found then one will be added automatically.
+    #   * :subscriberListIDs - An array of lists to send the campaign to. See http://www.campaignmonitor.com/api/required/#listid for more details.
+    #   * :listSegments - An array of Segment Names and their appropriate List ID s to send the campaign to.
+    #   * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Campaign object which was recently created.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.    
+    def self.create!(params)  
+        response = @@soap.createCampaign(
+           :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
+           :clientID => params[:clientID],
+           :campaignName => params[:campaignName],
+           :campaignSubject => params[:campaignSubject],
+           :fromName => params[:fromName],
+           :fromEmail => params[:fromEmail],
+           :replyTo => params[:replyTo],
+           :htmlUrl => params[:htmlUrl],
+           :textUrl => params[:textUrl],
+           :subscriberListIDs => params[:subscriberListIDs],
+           :listSegments => params[:listSegments]
+          )
+
+        campaign_id = handle_response response.campaign_CreateResult
+        Campaign.new( campaign_id, nil, params[:campaignName], nil, nil, :apiKey=> (params[:apiKey] || CAMPAIGN_MONITOR_API_KEY) )
+    end
+    
+    #Deletes an existing campaign.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised. 
+    def delete!
+      Campaign.delete!(@campaignID, :apiKey=> @apiKey)
+      self.campaignID, self.subject, self.sentDate, self.totalRecipients  = nil, nil, nil, nil
+    end
+
+    #Deletes an existing campaign.
+    #
+    #Available _opts_ argument are:
+    #   * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def self.delete!(campaign_id, opts={})
+      response = @@soap.deleteCampaign(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :campaignID => campaign_id)
+      handle_response response.campaign_DeleteResult
+    end
+    
+    #Gets a list of all subscribers who bounced for a given campaign, and the type of bounce (H=Hard Bounce, S=Soft Bounce).
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of <code>SubscriberBounce</code> objects, each of
+    #which consists of the subscribers <code>:emailAddress</code>, the <code>listID</code> they belong to, and the <code>bounceType</code>
+    #of bounce they experienced, whether hard or soft.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def bounces
+      response = @@soap.getCampaignBounces(:apiKey => @apiKey, :campaignID => @campaignID )
+      handle_response response.campaign_GetBouncesResult
+    end
+    
+    #Returns an array of Campaigning::List objects that a given campaign was sent to.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of Campaigning::List object.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def lists
+      response = @@soap.getCampaignLists(:apiKey => @apiKey, :campaignID => @campaignID )
+      lists = handle_response response.campaign_GetListsResult
+      lists.collect do |list|  
+        List.new(list.listID, list.name, :apiKey=> @apiKey)
+      end
+    end
+    
+    #Gets a list of all subscribers who opened a given campaign, and the number of times they opened the campaign.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of <code>SubscriberOpen</code> objects, each of
+    #which consists of the subscribers <code>:emailAddress</code>, the <code>listID</code> they belong to, and the <code>numberOfOpens</code>
+    #representing the number of times they opened the given campaign.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def opens
+      response = @@soap.getCampaignOpens(:apiKey => @apiKey, :campaignID => @campaignID )
+      handle_response response.campaign_GetOpensResult
+    end
+    
+    #Gets a list of all subscribers who clicked a link for a given campaign, the ID of the list they belong to,
+    #the links they clicked, and the number of times they clicked the link.
+    #
+    #Example of usage:
+    #
+    # campaign_obj.subscriber_clicks.each do |subscriber|
+    #   puts "Subscriber: #{subscriber.emailAddress}"
+    #   subscriber.clickedLinks.each do |clicked| 
+    #     puts "Clicked link: #{clicked.link} - Number of clicks: #{clicked.clicks}"
+    #   end
+    # end
+    #
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of <code>SubscriberClick</code> objects, each of which consists of
+    #the subscribers <code>emailAddress</code>, the <code>listID</code> representing list they belong to, and the <code>clickedLinks</code>array 
+    #representing the links they have clicked and the number of times they clicked each link.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def subscriber_clicks
+      response = @@soap.getSubscriberClicks(:apiKey => @apiKey, :campaignID => @campaignID )
+      handle_response response.campaign_GetSubscriberClicksResult
+    end
+    
+    #Gets a statistical summary, including number of recipients and open count, for a given campaign.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return summary statistical values about this particular campaign
+    #including the number of recipients, the number of total opens, the number of link clicks, the number of recipients
+    #who unsubscribed and the number who bounced.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def summary
+      response = @@soap.getCampaignSummary(:apiKey => @apiKey, :campaignID => @campaignID )
+      handle_response response.campaign_GetSummaryResult
+    end
+    
+    #Gets a list of all subscribers who unsubscribed for a given campaign.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a collection of SubscriberUnsubscribe objects, each of which consists
+    #of the <code>emailAddress</code> representing subscribers email address and the <code>listID</code> representing the list they belong to.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def unsubscribes
+      response = @@soap.getCampaignUnsubscribes(:apiKey => @apiKey, :campaignID => @campaignID )
+      handle_response response.campaign_GetUnsubscribesResult
+    end
+    
+    #Schedules an existing campaign for sending.
+    #
+    #The campaign must be imported with defined recipients. For campaigns with more than 5 recipients the user must have
+    #sufficient credits or their credit card details saved within the application for the campaign to be sent via the API.
+    #For campaigns with 5 recipients or less the user must have enough test campaigns remaining in their API account.
+    #For further information about credits for campaigns please check at: http://www.campaignmonitor.com/api/method/campaign-send/
+    #
+    #Available _params_ argument are:
+    #   * :confirmationEmail - The email address that the confirmation email that the campaign has been sent will go to.
+    #   * :sendDate - The date the campaign should be scheduled to be sent. To send a campaign immediately pass in "Immediately".
+    #                  This date should be in the users timezone and formatted as YYYY-MM-DD HH:MM:SS.
+    #
+    #*Return*:
+    #Upon a successful call, this method will return a Result object with the newly create Campaign's ID as the Code.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def send!(params)
+      response = @@soap.sendCampaign(
+        :apiKey => @apiKey,
+        :campaignID => @campaignID,
+        :confirmationEmail => params[:confirmationEmail],
+        :sendDate => params[:sendDate]
+         )
+      handle_response response.campaign_SendResult
+    end
+
+  end
+end