yyyc514-campaign_monitor 1.3.2

data/lib/campaign_monitor/helpers.rb

@@ -0,0 +1,27 @@
+class CampaignMonitor
+  module Helpers
+
+    def handle_response(response)      
+      return [] if response.empty?
+
+      if response["Code"].to_i == 0
+        # success!
+        yield(response)
+      elsif response["Code"].to_i == 100
+        raise InvalidAPIKey
+      else
+        # error!
+        raise ApiError, response["Code"] + ": " + response["Message"]
+      end      
+    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,211 @@
+require 'soap/wsdlDriver'
+
+class CampaignMonitor
+  # Provides access to the subscribers and info about subscribers
+  # associated with a Mailing List
+  class List < Base
+    include CampaignMonitor::Helpers
+
+    id_field "ListID"
+    name_field "Title"
+
+    VALID_ATTRIBUTES=%w{ConfirmOptIn UnsubscribePage ConfirmationSuccessPage ListID Title}
+
+    # Example
+    #  @list = new List(12345)
+    def initialize(attrs={})
+      super
+      @attributes=attrs
+    end
+
+    # Example
+    # 
+    # @list = @client.new_list.defaults
+
+    def defaults
+      defaults={"ConfirmOptIn" => "false",
+        "UnsubscribePage" => "",
+        "ConfirmationSuccessPage" => ""}
+      @attributes=defaults.merge(@attributes)
+      self
+    end
+
+    # AR like
+    def save
+      id ? Update : Create
+    end
+
+    # Loads a list by it's ID
+    #
+    # @list = List.GetDetail(1234)
+    def self.GetDetail(id)
+      list=self.new("ListID" => id)
+      list.GetDetail(true)
+      list.result.code == 101 ? nil : list
+    end
+    
+    # loads a list by it's ID
+    #
+    # @list = List.GetDetail(1234)
+    def self.[](k)
+      GetDetail(k)
+    end
+    
+    def GetDetail(overwrite=false)
+      @result=Result.new(cm_client.List_GetDetail("ListID" => id))
+      @attributes=@result.raw.merge(@attributes)
+      @attributes.merge!(@result.raw) if overwrite
+      @result.success?
+    end
+    
+    def Update
+      # if we're dealing with a half baked object that Client#lists has given
+      # us then we need to popular all the fields before we can attempt an update
+      unless @fully_baked
+        self.GetDetail
+        @fully_baked=true
+      end
+      @result=Result.new(cm_client.List_Update(@attributes))
+      @result.success?
+    end
+    
+    def Delete
+      @result=Result.new(cm_client.List_Delete("ListID" => id))
+      @result.success?
+    end
+    
+    def Create
+      @result=Result.new(cm_client.List_Create(@attributes))
+      self.id = @result.content if @result.success?
+      @result.success?
+    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=nil)
+      if custom_fields.nil?
+        Result.new(cm_client.Subscriber_Add("ListID" => self.id, "Email" => email, "Name" => name))
+      else
+        add_subscriber_with_custom_fields(email, name, custom_fields)
+      end
+    end
+    
+    def add_and_resubscribe(email, name=nil, custom_fields=nil)
+      if custom_fields.nil?
+        Result.new(cm_client.Subscriber_AddAndResubscribe("ListID" => self.id, "Email" => email, "Name" => name))        
+      else
+        add_and_resubscribe_with_custom_fields(email, name, custom_fields)
+      end
+    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
+
+    # email           The subscriber's email address.
+    # name            The subscriber's name.
+    # custom_fields   A hash of field name => value pairs.
+    def add_subscriber_with_custom_fields(email, name, custom_fields)
+      response = cm_client.using_soap do |driver|
+        driver.addSubscriberWithCustomFields \
+            :ApiKey       => cm_client.api_key,
+            :ListID       => self.id,
+            :Email        => email,
+            :Name         => name,
+            :CustomFields => { :SubscriberCustomField => custom_fields_array(custom_fields) }
+      end
+      
+      response.subscriber_AddWithCustomFieldsResult
+    end
+
+    # email           The subscriber's email address.
+    # name            The subscriber's name.
+    # custom_fields   A hash of field name => value pairs.
+    def add_and_resubscribe_with_custom_fields(email, name, custom_fields)      
+      response = cm_client.using_soap do |driver|
+        driver.addAndResubscribeWithCustomFields \
+            :ApiKey       => cm_client.api_key,
+            :ListID       => self.id,
+            :Email        => email,
+            :Name         => name,
+            :CustomFields => { :SubscriberCustomField => custom_fields_array(custom_fields) }
+      end
+
+      response.subscriber_AddAndResubscribeWithCustomFieldsResult
+    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
+    
+
+    protected
+    
+      # Converts hash of custom field name/values to array of hashes for the SOAP API.
+      def custom_fields_array(custom_fields)
+        arr = []
+        custom_fields.each do |key, value|
+          arr << { "Key" => key, "Value" => value }
+        end
+        arr
+      end
+
+  end
+end

data/lib/campaign_monitor/misc.rb

@@ -0,0 +1,46 @@
+class CampaignMonitor
+
+  # Encapsulates
+  class SubscriberBounce #:nodoc:
+    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 #:nodoc:
+    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 #:nodoc:
+    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 #:nodoc:
+    attr_reader :email_address, :list_id
+
+    def initialize(email_address, list_id)
+      @email_address = email_address
+      @list_id = list_id
+    end
+  end
+
+end

data/lib/campaign_monitor/result.rb

@@ -0,0 +1,31 @@
+class CampaignMonitor
+  # Encapsulates the response received from the CampaignMonitor webservice.
+  class Result
+    attr_reader :message, :code, :raw
+
+    def initialize(response)
+      @message = response["Message"]
+      @code = response["Code"].to_i
+      @raw = response
+    end
+
+    def success?
+      code == 0
+    end
+
+    def failed?
+      not success?
+    end
+
+    def content
+      # if we're a string (likely from SOAP)
+      return raw if raw.is_a?(String)
+      # if we're a hash
+      raw["__content__"]
+    end
+
+    alias :succeeded? :success?
+    alias :failure? :failed?
+
+  end
+end

data/lib/campaign_monitor/subscriber.rb

@@ -0,0 +1,43 @@
+class CampaignMonitor
+  # Provides the ability to add/remove subscribers from a list
+  class Subscriber < Base
+    include CampaignMonitor::Helpers
+
+    attr_accessor :email_address, :name, :date_subscribed
+
+    def initialize(email_address, name=nil, date=nil)
+      @email_address = email_address
+      @name = name
+      @date_subscribed = date_subscribed
+      super
+    end
+
+    # Example
+    #  @subscriber = Subscriber.new("ralph.wiggum@simpsons.net")
+    #  @subscriber.add(12345)
+    def add(list_id)
+      Result.new(cm_client.Subscriber_Add("ListID" => list_id, "Email" => @email_address, "Name" => @name))
+    end
+
+    # Example
+    #  @subscriber = Subscriber.new("ralph.wiggum@simpsons.net")
+    #  @subscriber.add_and_resubscribe(12345)
+    def add_and_resubscribe(list_id)
+      Result.new(cm_client.Subscriber_AddAndResubscribe("ListID" => list_id, "Email" => @email_address, "Name" => @name))
+    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/lib/campaign_monitor.rb

@@ -0,0 +1,270 @@
+require 'rubygems'
+require 'cgi'
+require 'net/http'
+require 'xmlsimple'
+require 'date'
+gem 'soap4r'
+
+require File.join(File.dirname(__FILE__), '../support/class_enhancements.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/helpers.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/misc.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/base.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/client.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/list.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/subscriber.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/result.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/campaign.rb')
+
+# 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>
+# Copyright:: Copyright (c) 2006 Jordan Brock <jordan@spintech.com.au>
+# 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[client_id] # find an existing client
+#   client = Client.new(attributes)
+#   client.Create
+#   client.Delete
+#   client.GetDetail
+#   client.UpdateAccessAndBilling
+#   client.UpdateBasics
+#   client.update # update basics, access, and billing
+#   client.lists # OR
+#   client.GetLists
+#   client.lists.build # to create a new unsaved list for a client
+#   client.campaigns # OR
+#   client.GetCampaigns 
+#
+# == LIST
+#   list = List[list_id] # find an existing list
+#   list = List.new(attributes)
+#   list.Create
+#   list.Delete
+#   list.Update
+#   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
+#
+class CampaignMonitor
+  include CampaignMonitor::Helpers
+  
+  class InvalidAPIKey < StandardError
+  end
+
+  class ApiError < StandardError
+  end
+  
+  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'
+    CampaignMonitor::Base.client=self
+   end
+
+   # Takes a CampaignMonitor API method name and set of parameters;
+   # returns an XmlSimple object with the response
+  def request(method, params)
+    request_xml=http_get(request_url(method, params))
+    begin
+      response = PARSER.xml_in(request_xml, { 'keeproot' => false,
+        'forcearray' => %w[List Campaign Subscriber Client SubscriberOpen SubscriberUnsubscribe SubscriberClick SubscriberBounce],
+        'noattr' => true })
+      response.delete('d1p1:type')
+      response.delete("d1p1:http://www.w3.org/2001/XMLSchema-instance:type")
+      response
+    # rescue XML::Parser::ParseError
+    rescue XML::Error
+      { "Code" => 500, "Message" => request_xml.split(/\r?\n/).first, "FullError" => request_xml }
+    end
+  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)
+    response=Net::HTTP.get_response(URI.parse(url))
+    response.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 = {})
+    puts "  CM: #{method_id} (#{params.inspect})" if $debug
+    res=request(method_id.id2name.gsub(/_/, '.'), params)
+    puts "    returning: #{res.inspect}" if $debug
+    res
+  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({"ClientID" => c["ClientID"], "CompanyName" => c["Name"]})}
+    end
+  end
+  
+  def new_client
+    Client.new(nil)
+  end
+  
+  def system_date
+    User_GetSystemDate()
+  end
+
+  def parsed_system_date
+    DateTime.strptime(system_date, timestamp_format)
+  end
+  
+  def countries
+    handle_response(User_GetCountries()) do | response |
+      response["string"]
+    end
+  end
+  
+  def timezones
+    handle_response(User_GetTimezones()) do | response |
+      response["string"]
+    end
+  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"].collect{|c| Campaign.new(c) }
+    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"].collect{|l| List.new({"ListID" => l["ListID"], "Title" => 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
+  def add_subscriber(list_id, email, name)
+    Result.new(Subscriber_Add("ListID" => list_id, "Email" => email, "Name" => name))
+  end
+  
+  def using_soap
+    driver = wsdl_driver_factory.create_rpc_driver
+    driver.wiredump_dev = STDERR if $debug
+    response = yield(driver)
+    driver.reset_stream
+    
+    response
+  end
+
+  protected
+
+    def wsdl_driver_factory
+      SOAP::WSDLDriverFactory.new("#{api_url}?WSDL")
+    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/support/class_enhancements.rb

@@ -0,0 +1,35 @@
+module ClassEnhancements
+
+def inherited_property(accessor, default = nil)
+    instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+      @#{accessor} = default
+
+      def set_#{accessor}(value)
+        @#{accessor} = value
+      end
+      alias #{accessor} set_#{accessor}
+
+      def get_#{accessor}
+        return @#{accessor} if instance_variable_defined?(:@#{accessor})
+        superclass.send(:get_#{accessor})
+      end
+    RUBY
+
+    # @path = default
+    #
+    # def set_path(value)
+    #   @path = value
+    # end
+    # alias_method path, set_path
+
+    # def get_path
+    #   return @path if instance_variable_defined?(:path)
+    #   superclass.send(:path)
+    # end
+  end
+  
+end
+
+class Class #:nodoc:
+  include ClassEnhancements
+end