reidab-campaign_monitor 1.3.3

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