turingstudio-campaign_monitor 1.3.1

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2006 Jordan Brock
+Copyright (c) 2009 The Turing Studio, 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/README.rdoc

@@ -0,0 +1,52 @@
+= campaign_monitor
+
+This RubyGem provides access to the Campaign Monitor API (http://www.campaignmonitor.com/api).
+
+Campaign Monitor recently made some changes to their API.
+
+This fork makes the following changes:
+
+    * host changed from http://app.campaignmonitor.com to http://api.createsend.com
+    * ID values are no longer sent #to_i because they are hex strings
+    * added support for subscribers with custom fields using SOAP API
+    * refactored gemspec to build on github
+    * misc. cleanup and refactoring
+
+
+== Pre-requisites
+
+An account with Campaign Monitor and the API Key. Accounts are free and can be created at
+http://www.campaignmonitor.com.
+
+== Resources
+
+=== Install
+gem install turingstudio-campaign_monitor
+
+=== Git Repository
+http://github.com/turingstudio/campaign-monitor-ruby
+
+
+== Usage
+
+  cm = CampaignMonitor.new # assumes you've set CAMPAIGN_MONITOR_API_KEY in your project
+
+  for client in cm.clients
+    for list in client.lists
+      client.name # => returns the name
+    
+      # modify a subscriber list
+      list.add_subscriber(email, name, custom_fields_hash)
+      list.remove_subscriber(email)
+      list.add_and_resubscribe(email, name, custom_fields_hash)
+    
+      # get subscriber list details
+      subscribers = list.active_subscribers(since_time)
+      unsubscribed = list.unsubscribed(since_time)
+      bounced = list.bounced(since_time)
+    end
+  
+    for campaign in client.campaigns
+  
+    end
+  end

data/Rakefile

@@ -0,0 +1,29 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+# read the contents of the gemspec, eval it, and assign it to 'spec'
+# this lets us maintain all gemspec info in one place. Nice and DRY.
+spec = eval(IO.read("campaign_monitor.gemspec"))
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{spec.name}-#{spec.version}}
+end
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'doc'
+  rd.options = spec.rdoc_options
+end

data/campaign_monitor.gemspec

@@ -0,0 +1,45 @@
+Gem::Specification.new do |s|
+  s.platform    = Gem::Platform::RUBY
+  s.name        = 'campaign_monitor'
+  s.version     = "1.3.1"
+  s.summary     = 'Provides access to the Campaign Monitor API.'
+  s.description = <<-EOF
+    A simple wrapper class that provides basic access to the Campaign Monitor API.
+  EOF
+  
+  s.author      = 'The Turing Studio, Inc.'
+  s.email       = 'operations@turingstudio.com'
+  s.homepage    = 'http://github.com/turingstudio/campaign-monitor-ruby/'
+  s.has_rdoc    = true
+  
+  s.requirements << 'none'
+  s.require_path = 'lib'
+  
+  s.add_dependency 'xml-simple', ['>= 1.0.11']
+  
+  s.files = [
+    'campaign_monitor.gemspec',
+    'init.rb',
+    'install.rb',
+    'MIT-LICENSE',
+    'Rakefile',
+    'README.rdoc',
+  
+    'lib/campaign_monitor.rb',
+    'lib/campaign_monitor/campaign.rb',
+    'lib/campaign_monitor/client.rb',
+    'lib/campaign_monitor/helpers.rb',
+    'lib/campaign_monitor/list.rb',
+    'lib/campaign_monitor/result.rb',
+    'lib/campaign_monitor/subscriber.rb',
+  
+    'support/faster-xml-simple/lib/faster_xml_simple.rb',
+    'support/faster-xml-simple/test/regression_test.rb',
+    'support/faster-xml-simple/test/test_helper.rb',
+    'support/faster-xml-simple/test/xml_simple_comparison_test.rb',
+  
+    'test/test_campaign_monitor.rb',
+  ]
+
+  s.test_file = 'test/test_campaign_monitor.rb'
+end

data/init.rb

@@ -0,0 +1 @@
+require 'campaign_monitor'

data/lib/campaign_monitor.rb

@@ -0,0 +1,289 @@
+# CampaignMonitor
+# A wrapper class to access the Campaign Monitor API. Written using the wonderful
+# Flickr interface by Scott Raymond as a guide on how to access remote web services
+#
+# For more information on the Campaign Monitor API, visit http://campaignmonitor.com/api
+#
+# Author::    Jordan Brock <jordan@spintech.com.au>, The Turing Studio, Inc. <operations@turingstudio.com>
+# Copyright:: Copyright (c) 2006 Jordan Brock <jordan@spintech.com.au>, Copyright (c) 2009 The Turing Studio, Inc. <operations@turingstudio.com>
+# License::   MIT <http://www.opensource.org/licenses/mit-license.php>
+#
+# USAGE:
+#   require 'campaign_monitor'
+#   cm = CampaignMonitor.new(API_KEY)     # creates a CampaignMonitor object
+#                                         # Can set CAMPAIGN_MONITOR_API_KEY in environment.rb
+#   cm.clients                            # Returns an array of clients associated with
+#                                         #   the user account
+#   cm.campaigns(client_id)
+#   cm.lists(client_id)
+#   cm.add_subscriber(list_id, email, name)
+#
+#  CLIENT
+#   client = Client.new(client_id)
+#   client.lists
+#   client.campaigns
+#
+#  LIST
+#   list = List.new(list_id)
+#   list.add_subscriber(email, name)
+#   list.remove_subscriber(email)
+#   list.active_subscribers(date)
+#   list.unsubscribed(date)
+#   list.bounced(date)
+#
+#  CAMPAIGN
+#   campaign = Campaign.new(campaign_id)
+#   campaign.clicks
+#   campaign.opens
+#   campaign.bounces
+#   campaign.unsubscribes
+#   campaign.number_recipients
+#   campaign.number_clicks
+#   campaign.number_opens
+#   campaign.number_bounces
+#   campaign.number_unsubscribes
+#
+#
+#  SUBSCRIBER
+#   subscriber = Subscriber.new(email)
+#   subscriber.add(list_id)
+#   subscriber.unsubscribe(list_id)
+#
+#  Data Types
+#   SubscriberBounce
+#   SubscriberClick
+#   SubscriberOpen
+#   SubscriberUnsubscribe
+#   Result
+#
+
+require 'rubygems'
+require 'cgi'
+require 'net/http'
+require 'xmlsimple'
+require 'date'
+
+$:.unshift(File.dirname(__FILE__))
+require 'campaign_monitor/helpers.rb'
+require 'campaign_monitor/client.rb'
+require 'campaign_monitor/list.rb'
+require 'campaign_monitor/subscriber.rb'
+require 'campaign_monitor/result.rb'
+require 'campaign_monitor/campaign.rb'
+
+class CampaignMonitor
+  include CampaignMonitor::Helpers
+  
+  attr_reader :api_key, :api_url
+  
+  # Replace this API key with your own (http://www.campaignmonitor.com/api/)
+  def initialize(api_key=CAMPAIGN_MONITOR_API_KEY)
+    @api_key = api_key
+    @api_url = 'http://api.createsend.com/api/api.asmx'
+   end
+   
+
+   # Takes a CampaignMonitor API method name and set of parameters;
+   # returns an XmlSimple object with the response
+  def request(method, params)
+    response = PARSER.xml_in(http_get(request_url(method, params)), { 'keeproot' => false,
+      'forcearray' => %w[List Campaign Subscriber Client SubscriberOpen SubscriberUnsubscribe SubscriberClick SubscriberBounce],
+      'noattr' => true })
+    response.delete('d1p1:type')
+    response
+  end
+
+  # Takes a CampaignMonitor API method name and set of parameters; returns the correct URL for the REST API.
+  def request_url(method, params={})
+    params.merge!('ApiKey' => api_key)
+    
+    query = params.collect do |key, value|
+      "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+    end.sort * '&'
+    
+    "#{api_url}/#{method}?#{query}"
+  end
+
+  # Does an HTTP GET on a given URL and returns the response body
+  def http_get(url)
+    Net::HTTP.get_response(URI.parse(url)).body.to_s
+  end
+
+  # By overriding the method_missing method, it is possible to easily support all of the methods
+  # available in the API
+  def method_missing(method_id, params = {})
+    request(method_id.id2name.gsub(/_/, '.'), params)
+  end
+
+  # Returns an array of Client objects associated with the API Key
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  @clients = @cm.clients
+  #
+  #  for client in @clients
+  #    puts client.name
+  #  end
+  def clients
+    handle_response(User_GetClients()) do |response|
+      response["Client"].collect{|c| Client.new(c["ClientID"], c["Name"])}
+    end
+  end
+  
+  def system_date
+    User_GetSystemDate()
+  end
+
+  def parsed_system_date
+    DateTime.strptime(system_date, timestamp_format)
+  end
+  
+  # Returns an array of Campaign objects associated with the specified Client ID
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  @campaigns = @cm.campaigns(12345)
+  #
+  #  for campaign in @campaigns
+  #    puts campaign.subject
+  #  end
+  def campaigns(client_id)
+    handle_response(Client_GetCampaigns("ClientID" => client_id)) do |response|
+      response["Campaign"].to_a.collect{|c| Campaign.new(c["CampaignID"], c["Subject"], c["SentDate"], c["TotalRecipients"].to_i)}
+    end
+  end
+
+  # Returns an array of Subscriber Lists for the specified Client ID
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  @lists = @cm.lists(12345)
+  #
+  #  for list in @lists
+  #    puts list.name
+  #  end
+  def lists(client_id)
+    handle_response(Client_GetLists("ClientID" => client_id)) do |response|
+      response["List"].to_a.collect{|l| List.new(l["ListID"], l["Name"])}
+    end
+  end
+
+  # A quick method of adding a subscriber to a list. Returns a Result object
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  result = @cm.add_subscriber(12345, "ralph.wiggum@simpsons.net", "Ralph Wiggum")
+  #
+  #  if result.succeeded?
+  #    puts "Subscriber Added to List"
+  #  end
+  # email           The subscriber's email address.
+  # name            The subscriber's name.
+  # custom_fields   A hash of field name => value pairs.
+  def add_subscriber(list_id, email, name, force = false, custom_fields = {})
+    if custom_fields.empty?
+      method = force ? 'Subscriber_AddAndResubscribe' : 'Subscriber_Add'        
+      response = send(method,
+        "ListID"  => list_id,
+        "Email"   => email,
+        "Name"    => name
+      )
+      Result.new(response)
+    else
+      if force
+        request_method = 'AddAndResubscribeWithCustomFields'
+        result_method = 'Subscriber.AddAndResubscribeWithCustomFieldsResult'
+      else
+        request_method = 'AddSubscriberWithCustomFields'
+        result_method = 'Subscriber.AddWithCustomFieldsResult'
+      end
+      
+      response = using_soap do |driver|
+        driver.send(request_method,
+          :ApiKey       => api_key,
+          :ListID       => list_id,
+          :Email        => email,
+          :Name         => name,
+          :CustomFields => { :SubscriberCustomField => custom_fields_array(custom_fields) }
+        )
+      end
+      
+      Result.new(response[result_method])
+    end
+  end
+  
+  def custom_fields_array(custom_fields)
+    arr = []
+    custom_fields.each do |key, value|
+      arr << { "Key" => key, "Value" => value }
+    end
+    arr
+  end
+
+  # Encapsulates
+  class SubscriberBounce
+    attr_reader :email_address, :bounce_type, :list_id
+
+    def initialize(email_address, list_id, bounce_type)
+      @email_address = email_address
+      @bounce_type = bounce_type
+      @list_id = list_id
+    end
+  end
+
+  # Encapsulates
+  class SubscriberOpen
+    attr_reader :email_address, :list_id, :opens
+
+    def initialize(email_address, list_id, opens)
+      @email_address = email_address
+      @list_id = list_id
+      @opens = opens
+    end
+  end
+
+  # Encapsulates
+  class SubscriberClick
+    attr_reader :email_address, :list_id, :clicked_links
+
+    def initialize(email_address, list_id, clicked_links)
+      @email_address = email_address
+      @list_id = list_id
+      @clicked_links = clicked_links
+    end
+  end
+
+  # Encapsulates
+  class SubscriberUnsubscribe
+    attr_reader :email_address, :list_id
+
+    def initialize(email_address, list_id)
+      @email_address = email_address
+      @list_id = list_id
+    end
+  end
+    
+end
+
+# If libxml is installed, we use the FasterXmlSimple library, that provides most of the functionality of XmlSimple
+# except it uses the xml/libxml library for xml parsing (rather than REXML). 
+# If libxml isn't installed, we just fall back on XmlSimple.
+
+PARSER =
+  begin
+    require 'xml/libxml'
+    # Older version of libxml aren't stable (bus error when requesting attributes that don't exist) so we
+    # have to use a version greater than '0.3.8.2'.
+    raise LoadError unless XML::Parser::VERSION > '0.3.8.2'
+    $:.push(File.join(File.dirname(__FILE__), '..', 'support', 'faster-xml-simple', 'lib'))
+    require 'faster_xml_simple' 
+    p 'Using libxml-ruby'
+    FasterXmlSimple
+  rescue LoadError
+    begin
+      require 'rexml-expansion-fix'
+    rescue LoadError => e
+      p 'Cannot load rexml security patch'
+    end
+    XmlSimple
+  end

data/lib/campaign_monitor/campaign.rb

@@ -0,0 +1,121 @@
+class CampaignMonitor
+  # Provides access to the information about a campaign
+  class Campaign
+    include CampaignMonitor::Helpers
+    
+    attr_reader :id, :subject, :sent_date, :total_recipients, :cm_client
+
+    def initialize(id=nil, subject=nil, sent_date=nil, total_recipients=nil)
+      @id = id
+      @subject = subject
+      @sent_date = sent_date
+      @total_recipients = total_recipients
+      @cm_client = CampaignMonitor.new
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  @subscriber_opens = @campaign.opens
+    #
+    #  for subscriber in @subscriber_opens
+    #    puts subscriber.email
+    #  end
+    def opens
+      handle_response(cm_client.Campaign_GetOpens("CampaignID" => self.id)) do |response|
+        response["SubscriberOpen"].collect{|s| SubscriberOpen.new(s["EmailAddress"], s["ListID"], s["NumberOfOpens"])}
+      end
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  @subscriber_bounces = @campaign.bounces
+    #
+    #  for subscriber in @subscriber_bounces
+    #    puts subscriber.email
+    #  end
+    def bounces
+      handle_response(cm_client.Campaign_GetBounces("CampaignID"=> self.id)) do |response|
+        response["SubscriberBounce"].collect{|s| SubscriberBounce.new(s["EmailAddress"], s["ListID"], s["BounceType"])}
+      end
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  @subscriber_clicks = @campaign.clicks
+    #
+    #  for subscriber in @subscriber_clicks
+    #    puts subscriber.email
+    #  end
+    def clicks
+      handle_response(cm_client.Campaign_GetSubscriberClicks("CampaignID" => self.id)) do |response|
+        response["SubscriberClick"].collect{|s| SubscriberClick.new(s["EmailAddress"], s["ListID"], s["ClickedLinks"])}
+      end
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  @subscriber_unsubscribes = @campaign.unsubscribes
+    #
+    #  for subscriber in @subscriber_unsubscribes
+    #    puts subscriber.email
+    #  end
+    def unsubscribes
+      handle_response(cm_client.Campaign_GetUnsubscribes("CampaignID" => self.id)) do |response|
+        response["SubscriberUnsubscribe"].collect{|s| SubscriberUnsubscribe.new(s["EmailAddress"], s["ListID"])}
+      end
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  puts @campaign.number_recipients
+    def number_recipients
+      @number_recipients ||= attributes[:number_recipients]
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  puts @campaign.number_opened
+    def number_opened
+      @number_opened ||= attributes[:number_opened]
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  puts @campaign.number_clicks
+    def number_clicks
+      @number_clicks ||= attributes[:number_clicks]
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  puts @campaign.number_unsubscribed
+    def number_unsubscribed
+      @number_unsubscribed ||= attributes[:number_unsubscribed]
+    end
+
+    # Example
+    #  @campaign = Campaign.new(12345)
+    #  puts @campaign.number_bounced
+    def number_bounced
+      @number_bounced ||= attributes[:number_bounced]
+    end
+
+    private
+    
+    def attributes
+      @attributes ||= fetch_attributes
+    end
+    
+    def fetch_attributes
+      summary = cm_client.Campaign_GetSummary('CampaignID' => self.id)
+      
+      {
+        :number_recipients   => summary['Recipients'].to_i,
+        :number_opened       => summary['TotalOpened'].to_i,
+        :number_clicks       => summary['Click'].to_i,
+        :number_unsubscribed => summary['Unsubscribed'].to_i,
+        :number_bounced      => summary['Bounced'].to_i
+      }
+    end
+  end
+end

data/lib/campaign_monitor/client.rb

@@ -0,0 +1,38 @@
+class CampaignMonitor
+  # Provides access to the lists and campaigns associated with a client
+  class Client
+    include CampaignMonitor::Helpers
+
+    attr_reader :id, :name, :cm_client
+
+    # Example
+    #  @client = new Client(12345)
+    def initialize(id, name=nil)
+      @id = id
+      @name = name
+      @cm_client = CampaignMonitor.new
+    end
+
+    # Example
+    #  @client = new Client(12345)
+    #  @lists = @client.lists
+    #
+    #  for list in @lists
+    #    puts list.name
+    #  end
+    def lists
+      cm_client.lists(self.id)
+    end
+
+    # Example
+    #  @client = new Client(12345)
+    #  @campaigns = @client.campaigns
+    #
+    #  for campaign in @campaigns
+    #    puts campaign.subject
+    #  end
+    def campaigns
+      cm_client.campaigns(self.id)
+    end
+  end
+end

data/lib/campaign_monitor/helpers.rb

@@ -0,0 +1,36 @@
+class CampaignMonitor
+  module Helpers
+
+    def handle_response(response)      
+      return [] if response.empty?
+
+      if response["Code"].to_i == 0
+        # success!
+        yield(response)
+      else
+        # error!
+        raise response["Code"] + " - " + response["Message"]
+      end      
+    end
+
+    def wsdl_driver_factory
+      SOAP::WSDLDriverFactory.new("#{api_url}?WSDL")
+    end
+
+    def using_soap
+      driver = wsdl_driver_factory.create_rpc_driver
+      response = yield(driver)
+      driver.reset_stream
+      response
+    end
+
+    def timestamp_format
+      '%Y-%m-%d %H:%M:%S'
+    end
+
+    def formatted_timestamp(datetime, format=timestamp_format)
+      datetime.strftime(format)
+    end
+    
+  end
+end

data/lib/campaign_monitor/list.rb

@@ -0,0 +1,94 @@
+require 'soap/wsdlDriver'
+
+class CampaignMonitor
+  # Provides access to the subscribers and info about subscribers
+  # associated with a Mailing List
+  class List
+    include CampaignMonitor::Helpers
+
+    attr_reader :id, :name, :cm_client
+
+    # Example
+    #  @list = new List(12345)
+    def initialize(id=nil, name=nil)
+      @id = id
+      @name = name
+      @cm_client = CampaignMonitor.new
+    end
+
+    # Example
+    #  @list = new List(12345)
+    #  result = @list.add_subscriber("ralph.wiggum@simpsons.net")
+    #
+    #  if result.succeeded?
+    #    puts "Added Subscriber"
+    #  end
+    def add_subscriber(email, name = nil, custom_fields = {})
+      cm_client.add_subscriber(self.id, email, name, false, custom_fields)
+    end
+    
+    def add_and_resubscribe(email, name = nil, custom_fields = {})
+      cm_client.add_subscriber(self.id, email, name, true, custom_fields)
+    end
+
+    # Example
+    #  @list = new List(12345)
+    #  result = @list.remove_subscriber("ralph.wiggum@simpsons.net")
+    #
+    #  if result.succeeded?
+    #    puts "Deleted Subscriber"
+    #  end
+    def remove_subscriber(email)
+      Result.new(cm_client.Subscriber_Unsubscribe("ListID" => self.id, "Email" => email))
+    end
+    
+    # Example
+    #  current_date = DateTime.new
+    #  @list = new List(12345)
+    #  @subscribers = @list.active_subscribers(current_date)
+    #
+    #  for subscriber in @subscribers
+    #    puts subscriber.email
+    #  end
+    def active_subscribers(date)
+      response = cm_client.Subscribers_GetActive('ListID' => self.id, 'Date' => formatted_timestamp(date))
+      handle_response(response) do
+        response['Subscriber'].collect{|s| Subscriber.new(s['EmailAddress'], s['Name'], s['Date'])}
+      end
+    end
+
+    # Example
+    #  current_date = DateTime.new
+    #  @list = new List(12345)
+    #  @subscribers = @list.unsubscribed(current_date)
+    #
+    #  for subscriber in @subscribers
+    #    puts subscriber.email
+    #  end
+    def unsubscribed(date)
+      date = formatted_timestamp(date) unless date.is_a?(String)
+      
+      response = cm_client.Subscribers_GetUnsubscribed('ListID' => self.id, 'Date' => date)
+      
+      handle_response(response) do
+        response['Subscriber'].collect{|s| Subscriber.new(s['EmailAddress'], s['Name'], s['Date'])}
+      end
+    end
+
+    # Example
+    #  current_date = DateTime.new
+    #  @list = new List(12345)
+    #  @subscribers = @list.bounced(current_date)
+    #
+    #  for subscriber in @subscribers
+    #    puts subscriber.email
+    #  end
+    def bounced(date)
+      response = cm_client.Subscribers_GetBounced('ListID' => self.id, 'Date' => formatted_timestamp(date))
+
+      handle_response(response) do
+        response["Subscriber"].collect{|s| Subscriber.new(s["EmailAddress"], s["Name"], s["Date"])}        
+      end
+    end
+  end
+end

data/lib/campaign_monitor/result.rb

@@ -0,0 +1,19 @@
+class CampaignMonitor
+  # Encapsulates the response received from the CampaignMonitor webservice.
+  class Result
+    attr_reader :message, :code
+
+    def initialize(response)
+      @message = response["Message"]
+      @code = response["Code"].to_i
+    end
+
+    def succeeded?
+      code == 0
+    end
+
+    def failed?
+      !succeeded?
+    end
+  end
+end

data/lib/campaign_monitor/subscriber.rb

@@ -0,0 +1,44 @@
+class CampaignMonitor
+  # Provides the ability to add/remove subscribers from a list
+  class Subscriber
+    include CampaignMonitor::Helpers
+
+    attr_accessor :email_address, :name, :date_subscribed
+    attr_reader :cm_client
+
+    def initialize(email_address, name=nil, date=nil)
+      @email_address = email_address
+      @name = name
+      @date_subscribed = date_subscribed
+      @cm_client = CampaignMonitor.new
+    end
+
+    # Example
+    #  @subscriber = Subscriber.new("ralph.wiggum@simpsons.net")
+    #  @subscriber.add(12345)
+    def add(list_id, custom_fields = {})
+      cm_client.add_subscriber(list_id, @email_address, @name, false, custom_fields)
+    end
+
+    # Example
+    #  @subscriber = Subscriber.new("ralph.wiggum@simpsons.net")
+    #  @subscriber.add_and_resubscribe(12345)
+    def add_and_resubscribe(list_id, custom_fields = {})
+      cm_client.add_subscriber(list_id, @email_address, @name, true, custom_fields)
+    end
+
+    # Example
+    #  @subscriber = Subscriber.new("ralph.wiggum@simpsons.net")
+    #  @subscriber.unsubscribe(12345)
+    def unsubscribe(list_id)
+      Result.new(cm_client.Subscriber_Unsubscribe("ListID" => list_id, "Email" => @email_address))
+    end
+
+    def is_subscribed?(list_id)
+      result = cm_client.Subscribers_GetIsSubscribed("ListID" => list_id, "Email" => @email_address)
+      return true if result == 'True'
+      return false if result == 'False'
+      raise "Invalid value for is_subscribed?: #{result}"
+    end
+  end
+end

data/support/faster-xml-simple/lib/faster_xml_simple.rb

@@ -0,0 +1,187 @@
+# 
+# Copyright (c) 2006 Michael Koziarski
+# 
+# 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.
+
+require 'rubygems'
+require 'xml/libxml'
+
+class FasterXmlSimple
+  Version = '0.5.0'
+  class << self
+    # Take an string containing XML, and returns a hash representing that 
+    # XML document.  For example:
+    # 
+    #   FasterXmlSimple.xml_in("<root><something>1</something></root>")
+    #   {"root"=>{"something"=>{"__content__"=>"1"}}}
+    #
+    # Faster XML Simple is designed to be a drop in replacement for the xml_in
+    # functionality of http://xml-simple.rubyforge.org
+    #
+    # The following options are supported:
+    # 
+    # * <tt>contentkey</tt>: The key to use for the content of text elements,
+    #   defaults to '\_\_content__'
+    # * <tt>forcearray</tt>: The list of elements which should always be returned
+    #   as arrays.  Under normal circumstances single element arrays are inlined.
+    # * <tt>suppressempty</tt>: The value to return for empty elements, pass +true+
+    #   to remove empty elements entirely.
+    # * <tt>keeproot</tt>:  By default the hash returned has a single key with the
+    #   name of the root element.  If the name of the root element isn't 
+    #   interesting to you, pass +false+. 
+    # * <tt>forcecontent</tt>:  By default a text element with no attributes, will 
+    #   be collapsed to just a string instead of a hash with a single key.  
+    #   Pass +true+ to prevent this.
+    #
+    #
+    def xml_in(string, options={})
+      new(string, options).out
+    end
+  end
+  
+  def initialize(string, options) #:nodoc:
+    @doc     = parse(string)
+    @options = default_options.merge options
+  end
+  
+  def out #:nodoc:
+    if @options['keeproot']
+      {@doc.root.name => collapse(@doc.root)}
+    else
+      collapse(@doc.root)
+    end
+  end
+  
+  private
+    def default_options
+      {'contentkey' => '__content__', 'forcearray' => [], 'keeproot'=>true}
+    end
+  
+    def collapse(element)
+      result = hash_of_attributes(element) 
+      if text_node? element
+        text = collapse_text(element)
+        result[content_key] = text if text =~ /\S/
+      elsif element.children?
+        element.inject(result) do |hash, child|
+          unless child.text?
+            child_result = collapse(child) 
+            (hash[child.name] ||= []) << child_result
+          end
+          hash
+        end
+      end
+      if result.empty?
+        return empty_element
+      end
+      # Compact them to ensure it complies with the user's requests
+      inline_single_element_arrays(result) 
+      remove_empty_elements(result) if suppress_empty?
+      if content_only?(result) && !force_content?
+        result[content_key]
+      else
+        result
+      end
+    end
+    
+    def content_only?(result)
+      result.keys == [content_key]
+    end
+  
+    def content_key
+      @options['contentkey']
+    end
+  
+    def force_array?(key_name)
+      Array(@options['forcearray']).include?(key_name)
+    end
+  
+    def inline_single_element_arrays(result)
+      result.each do |key, value|
+        if value.size == 1 && value.is_a?(Array) && !force_array?(key)
+          result[key] = value.first
+        end
+      end    
+    end
+  
+    def remove_empty_elements(result)
+      result.each do |key, value|
+        if value == empty_element
+          result.delete key
+        end
+      end
+    end
+    
+    def suppress_empty?
+      @options['suppressempty'] == true
+    end
+     
+    def empty_element
+      if !@options.has_key? 'suppressempty'
+        {}
+      else
+        @options['suppressempty']
+      end
+    end
+
+    # removes the content if it's nothing but blanks,  prevents
+    # the hash being polluted with lots of content like "\n\t\t\t" 
+    def suppress_empty_content(result)
+      result.delete content_key if result[content_key] !~ /\S/ 
+    end
+  
+    def force_content?
+      @options['forcecontent']
+    end
+  
+    # a text node is one with 1 or more child nodes which are
+    # text nodes, and no non-text children, there's no sensible
+    # way to support nodes which are text and markup like:
+    # <p>Something <b>Bold</b> </p>
+    def text_node?(element)
+      !element.text? && element.all? {|c| c.text?}
+    end
+  
+    # takes a text node, and collapses it into a string
+    def collapse_text(element)
+      element.map {|c| c.content } * ''
+    end
+  
+    def hash_of_attributes(element)
+      result = {}
+      element.each_attr do |attribute| 
+        name = attribute.name
+        name = [attribute.ns, attribute.name].join(':') if attribute.ns?
+        result[name] = attribute.value 
+      end
+      result
+    end
+  
+    def parse(string)
+      if string == ''
+        string = ' '
+      end
+      XML::Parser.string(string).parse
+    end
+end
+
+class XmlSimple # :nodoc:
+  def self.xml_in(*args)
+    FasterXmlSimple.xml_in *args
+  end
+end

data/support/faster-xml-simple/test/regression_test.rb

@@ -0,0 +1,47 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class RegressionTest < FasterXSTest
+  def test_content_nil_regressions
+    expected = {"asdf"=>{"jklsemicolon"=>{}}}
+    assert_equal expected, FasterXmlSimple.xml_in("<asdf><jklsemicolon /></asdf>")
+    assert_equal expected, FasterXmlSimple.xml_in("<asdf><jklsemicolon /></asdf>", 'forcearray'=>['asdf'])
+  end
+  
+  def test_s3_regression
+    str = File.read("test/fixtures/test-7.xml")
+    assert_nil FasterXmlSimple.xml_in(str)["AccessControlPolicy"]["AccessControlList"]["__content__"]
+  end
+  
+  def test_xml_simple_transparency
+    assert_equal XmlSimple.xml_in("<asdf />"), FasterXmlSimple.xml_in("<asdf />")
+  end
+  
+  def test_suppress_empty_variations
+    str = "<asdf><fdsa /></asdf>"
+    
+    assert_equal Hash.new, FasterXmlSimple.xml_in(str)["asdf"]["fdsa"]
+    assert_nil FasterXmlSimple.xml_in(str, 'suppressempty'=>nil)["asdf"]["fdsa"]
+    assert_equal '', FasterXmlSimple.xml_in(str, 'suppressempty'=>'')["asdf"]["fdsa"]
+    assert !FasterXmlSimple.xml_in(str, 'suppressempty'=>true)["asdf"].has_key?("fdsa")
+  end
+
+  def test_empty_string_doesnt_crash
+    assert_raise(XML::Parser::ParseError) do
+      silence_stderr do 
+        FasterXmlSimple.xml_in('')
+      end
+    end
+  end
+  
+  def test_keeproot_false
+    str = "<asdf><fdsa>1</fdsa></asdf>"
+    expected = {"fdsa"=>"1"}
+    assert_equal expected, FasterXmlSimple.xml_in(str, 'keeproot'=>false)
+  end
+  
+  def test_keeproot_false_with_force_content
+    str = "<asdf><fdsa>1</fdsa></asdf>"
+    expected = {"fdsa"=>{"__content__"=>"1"}}
+    assert_equal expected, FasterXmlSimple.xml_in(str, 'keeproot'=>false, 'forcecontent'=>true)
+  end
+end

data/support/faster-xml-simple/test/test_helper.rb

@@ -0,0 +1,17 @@
+
+require 'test/unit'
+require 'faster_xml_simple'
+
+class FasterXSTest < Test::Unit::TestCase
+  def default_test
+  end
+  
+  def silence_stderr
+    str = STDERR.dup
+    STDERR.reopen("/dev/null")
+    STDERR.sync=true
+    yield
+  ensure
+    STDERR.reopen(str)
+  end
+end

data/support/faster-xml-simple/test/xml_simple_comparison_test.rb

@@ -0,0 +1,46 @@
+require File.dirname(__FILE__) + '/test_helper'
+require 'yaml'
+
+class XmlSimpleComparisonTest < FasterXSTest
+  
+  # Define test methods
+  
+  Dir["test/fixtures/test-*.xml"].each do |file_name|
+    xml_file_name = file_name
+    method_name = File.basename(file_name, ".xml").gsub('-', '_')
+    yml_file_name = file_name.gsub('xml', 'yml')
+    rails_yml_file_name = file_name.gsub('xml', 'rails.yml')
+    class_eval <<-EOV, __FILE__, __LINE__
+      def #{method_name}
+        assert_equal YAML.load(File.read('#{yml_file_name}')), 
+              FasterXmlSimple.xml_in(File.read('#{xml_file_name}'), default_options )
+      end
+      
+      def #{method_name}_rails
+        assert_equal YAML.load(File.read('#{rails_yml_file_name}')), 
+              FasterXmlSimple.xml_in(File.read('#{xml_file_name}'), rails_options)
+      end
+    EOV
+  end
+  
+  def default_options
+    {
+       'keeproot'      => true, 
+       'contentkey'    => '__content__', 
+       'forcecontent'  => true, 
+       'suppressempty' => nil,
+       'forcearray'    => ['something-else']
+    }
+  end
+  
+  def rails_options
+    {
+      'forcearray'   => false,
+      'forcecontent' => true,
+      'keeproot'     => true,
+      'contentkey'   => '__content__'
+    }
+  end
+  
+
+end

data/test/test_campaign_monitor.rb

@@ -0,0 +1,93 @@
+require 'rubygems'
+require 'campaign_monitor'
+require 'test/unit'
+
+CAMPAIGN_MONITOR_API_KEY  = 'Your API key'
+CLIENT_NAME               = 'TestClient'
+LIST_NAME                 = 'TestList'
+CAMPAIGN_NAME             = 'TestCampaign'
+
+class CampaignMonitorTest < Test::Unit::TestCase
+  def setup
+    @cm = CampaignMonitor.new    
+  end
+  
+  def test_has_clients
+    clients = @cm.clients
+    assert clients.size > 0
+  end
+  
+  def test_default_client
+    client = default_client
+    assert_not_nil client
+    assert_equal CLIENT_NAME, client.name
+  end
+  
+  def test_has_lists
+    lists = default_client.lists
+    assert lists.size > 0
+  end
+  
+  def test_default_list
+    list = default_list
+    assert_not_nil list
+    assert_equal LIST_NAME, list.name
+  end
+  
+  def test_add_subscriber_fail
+    result = @cm.add_subscriber(1, 2, 3)
+    assert_equal result.code, 101
+    assert_not_nil result.message
+  end
+  
+  def test_list_add_subscriber
+    list = default_list
+    assert_success list.add_and_resubscribe('first@example.com', 'Test Subscriber')
+    assert_success list.remove_subscriber('first@example.com')
+  end
+  
+  def test_list_add_subscriber_fail
+    list = default_list
+    list.remove_subscriber('first@example.com')
+    assert_failure list.add_subscriber('first@example.com', 'Test Subscriber')
+  end
+  
+  def test_add_and_resubscribe_with_custom_fields
+    list = default_list
+    assert_success list.add_and_resubscribe('third@example.com', 'Test Subscriber', 'TestKey' => 'TestValue')
+    assert_success list.remove_subscriber('third@example.com')
+  end
+  
+  def test_add_with_custom_fields
+    list = default_list
+    assert_success list.add_subscriber('fourth@example.com', 'Test Subscriber', 'TestKey' => 'TestValue')
+    list.remove_subscriber('fourth@example.com')
+  end
+  
+  def test_campaigns
+    client = default_client
+    assert_equal client.campaigns, []
+  end
+  
+  protected
+  
+  def assert_success(result)
+    assert result.succeeded?, result.message      
+  end
+  
+  def assert_failure(result)
+    assert result.failed?
+  end
+  
+  def default_client(clients = @cm.clients)
+    clients.detect { |c| c.name == CLIENT_NAME }
+  end
+  
+  def default_list(lists = default_client.lists)
+    lists.detect { |l| l.name == LIST_NAME }
+  end
+  
+  def default_campaign(campaigns = default_client.campaigns)
+    campaigns.detect { |c| c.name == CAMPAIGN_NAME }
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: turingstudio-campaign_monitor
+version: !ruby/object:Gem::Version 
+  version: 1.3.1
+platform: ruby
+authors: 
+- The Turing Studio, Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-11 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: xml-simple
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.0.11
+    version: 
+description: A simple wrapper class that provides basic access to the Campaign Monitor API.
+email: operations@turingstudio.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- campaign_monitor.gemspec
+- init.rb
+- install.rb
+- MIT-LICENSE
+- Rakefile
+- README.rdoc
+- lib/campaign_monitor.rb
+- lib/campaign_monitor/campaign.rb
+- lib/campaign_monitor/client.rb
+- lib/campaign_monitor/helpers.rb
+- lib/campaign_monitor/list.rb
+- lib/campaign_monitor/result.rb
+- lib/campaign_monitor/subscriber.rb
+- support/faster-xml-simple/lib/faster_xml_simple.rb
+- support/faster-xml-simple/test/regression_test.rb
+- support/faster-xml-simple/test/test_helper.rb
+- support/faster-xml-simple/test/xml_simple_comparison_test.rb
+- test/test_campaign_monitor.rb
+has_rdoc: true
+homepage: http://github.com/turingstudio/campaign-monitor-ruby/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: 
+- none
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Provides access to the Campaign Monitor API.
+test_files: 
+- test/test_campaign_monitor.rb