reidab-campaign_monitor 1.3.3

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,217 @@
+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|
+          if value.is_a? Array
+            value.each do |array_value|
+              arr << { "Key" => key, "Value" => array_value }
+            end
+          else
+            arr << { "Key" => key, "Value" => value }
+          end
+        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['__content__'] == 'True'
+      return false if result['__content__'] == 'False'
+      raise "Invalid value for is_subscribed?: #{result}"
+    end
+  end
+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

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