MattHall-campaign_monitor 1.3.2.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Jordan Brock
+
+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 patientslikeme-campaign_monitor
+
+=== Git Repository
+http://github.com/patientslikeme/campaign_monitor
+
+
+== 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,31 @@
+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
+
+task :default => [:test]
+
+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/TODO

@@ -0,0 +1,6 @@
+* Decide on convents about when to raise and when to return true/false
+
+  So far I've kind of taken the stance if we're retrieving a list and there
+  are only two possible failures (APIKey or primary key) to raise if there
+  is an error but for update/save/create operations to return true/false
+  and then let the user probe @object.result for more details

data/campaign_monitor.gemspec

@@ -0,0 +1,53 @@
+Gem::Specification.new do |s|
+  s.platform    = Gem::Platform::RUBY
+  s.name        = 'campaign_monitor'
+  s.version     = "1.3.2.2"
+  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      = 'Jeremy Weiskotten'
+  s.email       = 'jweiskotten@patientslikeme.com'
+  s.homepage    = 'http://github.com/patientslikeme/campaign_monitor/'
+  s.has_rdoc    = true
+  
+  s.requirements << 'none'
+  s.require_path = 'lib'
+
+  s.add_dependency 'xml-simple', ['>= 1.0.11']
+  s.add_dependency 'soap4r', ['>= 1.5.8']
+
+  s.files = [
+      'campaign_monitor.gemspec',
+      'init.rb',
+      'install.rb',
+      'MIT-LICENSE',
+      'Rakefile',
+      'README.rdoc',
+      'TODO',
+      
+      'lib/campaign_monitor.rb',
+      'lib/campaign_monitor/base.rb',
+      'lib/campaign_monitor/misc.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/class_enhancements.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/campaign_monitor_test.rb',
+      'test/campaign_test.rb',
+      'test/client_test.rb',
+      'test/list_test.rb',
+      'test/test_helper.rb'
+    ]
+
+  s.test_file = 'test/campaign_monitor_test.rb'
+end

data/init.rb

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

data/lib/campaign_monitor/base.rb

@@ -0,0 +1,55 @@
+class CampaignMonitor
+  # Provides access to the lists and campaigns associated with a client
+  class Base
+
+    attr_reader :result, :attributes, :cm_client
+
+    @@client=nil
+
+    def self.client
+      @@client
+    end
+    
+    def self.client=(a)
+      @@client=a
+    end
+    
+    def [](k)
+      if m=self.class.get_data_types[k]
+        @attributes[k].send(m)
+      else
+        @attributes[k]
+      end
+    end
+    
+    def []=(k,v)
+      @attributes[k]=v
+    end
+    
+    def initialize(*args)
+      @attributes={}
+      @cm_client=@@client
+    end
+    
+    # id and name field stuff
+    
+    inherited_property "id_field", "id"
+    inherited_property "name_field", "name"
+    inherited_property "data_types", {}
+    
+    def id
+      @attributes[self.class.get_id_field]
+    end
+    
+    def id=(v)
+      @attributes[self.class.get_id_field]=v
+    end
+    
+    def name
+      @attributes[self.class.get_name_field]
+    end
+    
+  end
+  
+end
+    

data/lib/campaign_monitor/campaign.rb

@@ -0,0 +1,240 @@
+class CampaignMonitor
+
+  # The Client class aims to impliment the full functionality of the CampaignMonitor 
+  # Clients API as detailed at: http://www.campaignmonitor.com/api/
+  # === Attributes
+  #
+  # Attriutes can be read and set as if Campaign were a Hash
+  #
+  #   @client["CompanyName"]="Road Running, Inc."
+  #   @client["ContactName"] => "Wiley Coyote"
+  #
+  # Convenience attribute readers are provided for name and id
+  #
+  #   @campaign.id == @client["CampaignID"]
+  #   @campaign.name == @client["CampaignName"]
+  #
+  # === API calls supported
+  # 
+  # * Campaign.Create
+  # * Campaign.Send
+  # * Campaign.GetBounces
+  # * Campaign.GetLists
+  # * Campaign.GetOpens
+  # * Campaign.GetSubscriberClicks
+  # * Campaign.GetUnsubscribes
+  # * Campaign.GetSummary
+  #
+  class Campaign < Base
+    include CampaignMonitor::Helpers
+    id_field "CampaignID"
+    name_field "Subject"
+    
+    class MissingParameter < StandardError
+    end
+    
+    data_types "TotalRecipients" => "to_i"
+
+    def initialize(attrs={})
+      super
+      @attributes=attrs
+    end
+
+    # Calls Campaign.Create
+    # It will return true if successful and false if not.
+    # Campaign#result will have the result of the API call
+    #
+    # Example
+    #   @camp=@client.new_campaign
+    #   @camp["CampaignName"]="Yummy Gummy Bears"
+    #   @camp["CampaignSubject"]="Yummy Gummy Bears"
+    #   @camp["FromName"]="Mr Yummy"
+    #   @camp["FromEmail"]="yummy@gummybears.com"
+    #   @camp["ReplyTo"]="support@gummybears.com"
+    #   @camp["HtmlUrl"]="http://www.gummybears.com/newsletter2009.html"
+    #   @camp["TextUrl"]="http://www.gummybears.com/newsletter2009.txt"
+    #   @camp.Create
+    def Create
+      required_params=%w{CampaignName CampaignSubject FromName FromEmail ReplyTo HtmlUrl TextUrl}
+      required_params.each do |f|
+        raise MissingParameter, "'#{f}' is required to call Create" unless self[f]
+      end
+      response = cm_client.using_soap do |driver|
+        opts=attributes.merge(:ApiKey => cm_client.api_key, :SubscriberListIDs => @lists.map {|x| x.id})
+        driver.createCampaign opts
+      end
+      @result=Result.new(response["Campaign.CreateResult"])
+      self.id=@result.content if @result.success?
+      @result.success?
+    end
+    
+    # Calls Campaign.Send
+    # It will return true if successful and false if not.
+    # Campaign#result will have the result of the API call
+    #
+    # Example
+    #   @camp=@client.new_campaign(attributes)
+    #   @camp.Create
+    #   @camp.Send("ConfirmationEmail" => "bob@aol.com", "SendDate" => "Immediately")
+    def Send(options={})
+      required_params=%w{ConfirmationEmail SendDate}
+      required_params.each do |f|
+        raise MissingParameter, "'#{f}' is required to call Send" unless options[f]
+      end
+      options.merge!("CampaignID" => self.id)
+      @result=Result.new(@cm_client.Campaign_Send(options))
+      @result.success?
+    end
+
+    # Calls Campaign.GetLists.  Often you probably should just use Campaign#lists
+    # It will raise an ApiError if an error occurs
+    # Campaign#result will have the result of the API call
+    #
+    # Example
+    #   @camp=@client.campaigns.first
+    #   @camp.GetLists
+    def GetLists
+      handle_response(@cm_client.Campaign_GetLists(:CampaignID => id)) do |response|
+        @result=Result.new(response)
+        @lists=response["List"].collect{|l| List.new({"ListID" => l["ListID"], "Title" => l["Name"]})}
+      end
+    end
+
+    # Creates a new list object with the given id.
+    # You'll still need to call another method to load data or actually do anything useful
+    # as this method just generators a new object and doesn't hit the API at all.  This was
+    # added as a quick way to setup an object to request data from it
+    #
+    # Example
+    #   @campaign=Campaign[1234]
+    #   @campaign.lists.each do ... 
+    def self.[](id)
+      Campaign.new("CampaignID" => id)
+    end
+
+    # Convenience method for accessing or adding lists to a new (uncreated) campaign
+    # Calls GetLists behind the scenes if needed
+    #
+    # Example
+    #   @camp=@client.campaigns.first
+    #   @camp.lists.each do
+    #   
+    #   @camp=@client.new_campaign(attributes)
+    #   @camp.lists << @client.lists.first
+    #   @camp.Create
+    def lists
+      # pull down the list of lists if we have an id
+      self.GetLists if @lists.nil? and id
+      @lists||=[]
+    end
+
+    # Example
+    #  @campaign = Campaign[12345]
+    #  @subscriber_opens = @campaign.opens
+    #
+    #  for subscriber in @subscriber_opens
+    #    puts subscriber.email
+    #  end
+    def GetOpens
+      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
+    alias opens GetOpens
+
+    # Example
+    #  @campaign = Campaign[12345]
+    #  @subscriber_bounces = @campaign.bounces
+    #
+    #  for subscriber in @subscriber_bounces
+    #    puts subscriber.email
+    #  end
+    def GetBounces
+      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
+    alias bounces GetBounces
+
+    # Example
+    #  @campaign = Campaign[12345]
+    #  @subscriber_clicks = @campaign.clicks
+    #
+    #  for subscriber in @subscriber_clicks
+    #    puts subscriber.email
+    #  end
+    def GetSubscriberClicks
+      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
+    alias clicks GetSubscriberClicks
+
+    # Example
+    #  @campaign = Campaign[12345]
+    #  @subscriber_unsubscribes = @campaign.unsubscribes
+    #
+    #  for subscriber in @subscriber_unsubscribes
+    #    puts subscriber.email
+    #  end
+    def GetUnsubscribes
+      handle_response(cm_client.Campaign_GetUnsubscribes("CampaignID" => self.id)) do |response|
+        response["SubscriberUnsubscribe"].collect{|s| SubscriberUnsubscribe.new(s["EmailAddress"], s["ListID"])}
+      end
+    end
+    alias unsubscribes GetUnsubscribes
+
+    # hook up the old API calls
+    def method_missing(m, *args)
+      if %w{number_bounced number_unsubscribed number_clicks number_opened number_recipients}.include?(m.to_s)
+        summary[m]
+      else
+        super
+      end
+    end
+
+    # Calls Campaign.GetSummary.  OYou probably should just use Campaign#summary which caches results
+    # It will raise ApiError if an error occurs
+    # Campaign#result will have the result of the API call
+    #
+    # Example
+    #   @camp=@client.campaigns.first
+    #   @camp.GetSummary["Clicks"]
+    def GetSummary
+      handle_response(cm_client.Campaign_GetSummary('CampaignID' => self.id)) do |response|
+        @result=Result.new(response)
+        @summary=parse_summary(@result.raw)
+      end
+      @summary
+    end
+
+    # Convenience method for accessing summary details of a campaign
+    #
+    # Examples
+    #   @camp.summary["Recipients"]    
+    #   @camp.summary['Recipients']
+    #   @camp.summary['TotalOpened']
+    #   @camp.summary['Clicks']
+    #   @camp.summary['Unsubscribed']
+    #   @camp.summary['Bounced']
+    def summary(refresh=false)
+      self.GetSummary if refresh or @summary.nil?
+      @summary
+    end
+
+    private
+      def parse_summary(summary)
+        @summary = {
+          :number_recipients   => summary['Recipients'].to_i,
+          :number_opened       => summary['TotalOpened'].to_i,
+          :number_clicks       => summary['Clicks'].to_i,
+          :number_unsubscribed => summary['Unsubscribed'].to_i,
+          :number_bounced      => summary['Bounced'].to_i
+        }
+        summary.each do |key, value|
+          @summary[key]=value.to_i
+        end
+        @summary
+      end
+  end
+end

data/lib/campaign_monitor/client.rb

@@ -0,0 +1,228 @@
+class CampaignMonitor
+  # Provides access to the lists and campaigns associated with a client
+  class ClientLists < Array
+    def initialize(v,parent)
+      @parent=parent
+      super(v)
+    end
+    def build(attrs={})
+      List.new(attrs.merge(:ClientID => @parent.id))
+    end
+  end
+
+  # The Client class aims to impliment the full functionality of the CampaignMonitor 
+  # Clients API as detailed at: http://www.campaignmonitor.com/api/
+  # === Attributes
+  #
+  # Attriutes can be read and set as if Client were a Hash
+  #
+  #   @client["CompanyName"]="Road Running, Inc."
+  #   @client["ContactName"] => "Wiley Coyote"
+  #
+  # Convenience attribute readers are provided for name and id
+  #
+  #   @client.id == @client["ClientID"]
+  #   @client.name == @client["CompanyName"]
+  #
+  # === API calls supported
+  # 
+  # * Client.Create
+  # * Client.Delete
+  # * Client.GetCampaigns
+  # * Client.GetDetail
+  # * Client.GetLists
+  # * Client.UpdateAccessAndBilling
+  # * Client.UpdateBasics
+  # 
+  # === Not yet supported
+  #
+  # * Client.GetSegments - TODO
+  # * Client.GetSuppressionList - TODO
+  class Client < Base
+    include CampaignMonitor::Helpers
+    id_field "ClientID"
+    name_field "CompanyName"
+
+    data_types "AccessLevel" => "to_i"
+
+    # we will assume if something isn't a basic attribute that it's a AccessAndBilling attribute
+    BASIC_ATTRIBUTES=%w{CompanyName ContactName EmailAddress Country Timezone}
+
+    # Creates a new client that you can later create (or load)
+    # The prefered way to load a client is using Client#[] however
+    #
+    # Example
+    #
+    #  @client = Client.new(attributes)
+    #  @client.Create
+    #
+    #  @client = Client.new("ClientID" => 12345)
+    #  @client.GetDetails
+    def initialize(attrs={})
+      super
+      @attributes=attrs
+    end
+
+    # Calls Client.GetLists and returns a collection of CM::Campaign objects
+    #
+    # Example
+    #  @client = @cm.clients.first
+    #  @new_list = @client.lists.build
+    #  @lists = @client.lists
+    #
+    #  for list in @lists
+    #    puts list.name # a shortcut for list["Title"]
+    #  end
+    def GetLists
+      ClientLists.new(cm_client.lists(self.id), self)
+    end
+
+    alias lists GetLists
+
+    # Calls Client.GetCampaigns and returns a collection of CM::List objects
+    #
+    # Example
+    #  @client = @cm.clients.first
+    #  @campaigns = @client.campaigns
+    #
+    #  for campaign in @campaigns
+    #    puts campaign.subject
+    #  end
+    def GetCampaigns
+      cm_client.campaigns(self.id)
+    end
+
+    alias campaigns GetCampaigns
+    
+    def new_campaign(attrs={})
+      Campaign.new(attrs.merge("ClientID" => self.id))
+    end
+    
+    
+    # Calls Client.GetDetails to load a specific client
+    # Client#result will have the result of the API call
+    #
+    # Example
+    # 
+    #   @client=Client[12345]
+    #   puts @client.name if @client.result.success?
+    def self.[](id)
+      client=self.new("ClientID" => id)
+      client.GetDetail(true)
+      client.result.code == 102 ? nil : client
+    end
+  
+    # Calls Client.GetDetails
+    # This is needed because often if you're working with a list of clients you really only
+    # have their company name when what you want is the full record.
+    # It will return true if successful and false if not.
+    # Client#result will have the result of the API call
+    #
+    # Example
+    #
+    #   @client=@cm.clients.first
+    #   @client["CompanyName"]="Ben's Widgets"
+    #   @client["ContactName"] => nil
+    #   @client.GetDetail
+    #   @client["ContactName"] => "Ben Wilder"
+    def GetDetail(overwrite=false)
+      @result=Result.new(cm_client.Client_GetDetail("ClientID" => id))
+      return false if @result.failed?
+      @flatten={}
+      @flatten.merge!(@result.raw["BasicDetails"])
+      @flatten.merge!(@result.raw["AccessAndBilling"])
+      # TODO - look into
+      # map {} to nil - some weird XML converstion issue?
+      @flatten=@flatten.inject({}) { |sum,a| sum[a[0]]=a[1]=={} ? nil : a[1]; sum }
+      @attributes=@flatten.merge(@attributes)
+      @attributes.merge!(@flatten) if overwrite
+      @fully_baked=true if @result.success?
+      @result.success?
+    end
+    
+    # This is just a convenience method that calls both Client.UpdateBasics and Client.UpdateAccessAndBilling.
+    # It will return true if successful and false if not.
+    # Client#result will have the result of the API call
+    #
+    # Example
+    #   @client=@cm.clients.first
+    #   @client["CompanyName"]="Ben's Widgets"
+    #   @client.update
+    def update
+      self.UpdateBasics
+      self.UpdateAccessAndBilling if result.success?
+      @result.success?
+    end
+
+    # Calls Client.UpdateAccessAndBilling
+    # This will also call GetDetails first to prepoluate any empty fields the API call needs
+    # It will return true if successful and false if not.
+    # Client#result will have the result of the API call
+    #
+    # Example
+    #   @client=@cm.clients.first
+    #   @client["Currency"]="USD"
+    #   @client.UpdateAccessAndBilling
+    def UpdateAccessAndBilling
+      fully_bake
+      @result=Result.new(cm_client.Client_UpdateAccessAndBilling(@attributes))
+      @result.success? 
+    end
+
+    # Calls Client.UpdateBasics
+    # This will also call GetDetails first to prepoluate any empty fields the API call needs
+    # It will return true if successful and false if not.
+    # Client#result will have the result of the API call
+    #
+    # Example
+    #   @client=@cm.clients.first
+    #   @client["CompanyName"]="Ben's Widgets"
+    #   @client.UpdateBasics
+    def UpdateBasics
+      fully_bake
+      @result=Result.new(cm_client.Client_UpdateBasics(@attributes))
+      @result.success? 
+    end
+
+    # Calls Client.Create
+    # It will return true if successful and false if not.
+    # Client#result will have the result of the API call
+    #
+    # Example
+    #   @client=CampaignMonitor::Client.new
+    #   @client["CompanyName"]="Ben's Widgets"
+    #   @client["ContactName"]="Ben Winters"
+    #   @client["Country"]=@cm.countries.first
+    #   @client["Timezone"]=@cm.timezones.first
+    #   ...
+    #   @client.Create
+    def Create
+      @result=Result.new(cm_client.Client_Create(@attributes))
+      self.id = @result.content if @result.success?
+      @result.success?
+    end
+
+    # Calls Client.Delete.
+    # It will return true if successful and false if not.
+    # Client#result will have the result of the API call
+    #
+    # Example
+    #   @client=@cm.clients.first
+    #   @client.Delete
+    def Delete
+      @result=Result.new(cm_client.Client_Delete("ClientID" => id))
+      @result.success?
+    end
+    
+    private 
+
+    #:nodoc:
+    def fully_bake 
+      unless @fully_baked
+        self.GetDetail
+        @fully_baked=true
+      end
+    end
+    
+  end
+end