hominid 1.2.1 → 2.0.0

data/lib/hominid/base.rb

@@ -0,0 +1,85 @@
+module Hominid
+  class Base
+
+    # MailChimp API Documentation: http://www.mailchimp.com/api/1.2/
+    MAILCHIMP_API_VERSION = "1.2"
+
+    def initialize(config = {})
+      if defined?(Rails.root) && (!config || config.empty?)
+        config = YAML.load(File.open("#{Rails.root}/config/hominid.yml"))[Rails.env].symbolize_keys
+      end
+      api_endpoint = config[:api_key].split('-').last
+      config.merge(:username => config[:username].to_s, :password => config[:password].to_s)
+      defaults = {:send_welcome       => false,
+                  :double_opt_in      => false,
+                  :update_existing    => true,
+                  :replace_interests  => true,
+                  :merge_tags         => {}}
+      @config = defaults.merge(config).freeze
+      @chimpApi = XMLRPC::Client.new2("http://#{api_endpoint}.api.mailchimp.com/#{MAILCHIMP_API_VERSION}/")
+    end
+
+    # Security related methods
+    # --------------------------------
+
+    def add_api_key
+      @chimpApi.call("apikeyAdd", *@config.values_at(:username, :password, :api_key))
+    end
+
+    def expire_api_key
+      @chimpApi.call("apikeyExpire", *@config.values_at(:username, :password, :api_key))
+    end
+
+    def api_keys(include_expired = false)
+      username, password = *@config.values_at(:username, :password)
+      @chimpApi.call("apikeys", username, password, include_expired)
+    end
+
+    # Used internally by Hominid
+    # --------------------------------
+
+    # handle common cases for which the Mailchimp API would raise Exceptions
+    def clean_merge_tags(merge_tags)
+      return {} unless merge_tags.is_a? Hash
+      merge_tags.each do |key, value|
+        if merge_tags[key].is_a? String
+          merge_tags[key] = value.gsub("\v", '')
+        elsif merge_tags[key].nil?
+          merge_tags[key] = ''
+        end
+      end
+    end
+
+    def apply_defaults_to(options)
+      @config.merge(options)
+    end
+
+    def call(method, *args)
+      @chimpApi.call(method, @config[:api_key], *args)
+    rescue XMLRPC::FaultException => error
+      case error.faultCode
+      when 230
+        raise AlreadySubscribed.new(error)
+      when 231
+        raise AlreadyUnsubscribed.new(error)
+      when 232
+        raise NotExists.new(error)
+      when 233, 215
+        raise NotSubscribed.new(error)
+      else
+        raise HominidError.new(error)
+      end
+    rescue RuntimeError => error
+      if error.message =~ /Wrong type NilClass\. Not allowed!/
+        hashes = args.select{|a| a.is_a? Hash}
+        errors = hashes.select{|k, v| v.nil? }.collect{ |k, v| "#{k} is Nil." }.join(' ')
+        raise CommunicationError.new(errors)
+      else
+        raise error
+      end
+    rescue Exception => error
+      raise CommunicationError.new(error.message)
+    end
+  end
+end
+

data/lib/hominid/campaign.rb

@@ -0,0 +1,172 @@
+module Hominid
+
+  class Campaign < Base
+
+    # Campaign related methods
+    # --------------------------------
+
+    attr_reader :campaign_id
+    attr_reader :attributes
+
+    def initialize(*args)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      raise StandardError.new('Please provide a Campaign ID.') unless options[:id]
+      @campaign_id = options.delete(:id)
+      @attributes = options.delete(:attributes)
+      super(options)
+    end
+
+    def self.all
+      # Get all campaigns for this mailchimp account
+      new(:id => 0).call("campaigns").to_a.collect { |c| Campaign.new(:id => c.delete('id'), :attributes => c) }
+    end
+
+    def self.find_by_list_name(list_name)
+      new(:id => 0).call("campaigns", {:list_id => List.find_by_name(list_name).list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
+    end
+
+    def self.find_by_list_id(list_id)
+      # Find all campaigns for the given list
+      new(:id => 0).call("campaigns", {:list_id => list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
+    end
+
+    def self.find_by_title(title)
+      # Find campaign by title
+      all.find { |c| c.attributes['title'] =~ /#{title}/ }
+    end
+
+    def self.find_by_type(type)
+      # Find campaign by type. Possible choices are:
+      #   'regular'
+      #   'plaintext'
+      #   'absplit'
+      #   'rss'
+      #   'inspection'
+      #   'trans'
+      #   'auto'
+      all.find { |campaign| campaign.attributes['type'] =~ /#{type}/ }
+    end
+
+    def self.find_by_web_id(web_id)
+      # Find campaigns by web_id
+      all.find { |campaign| campaign.attributes['web_id'] =~ /#{web_id}/ }
+    end
+
+    def self.find_by_id(id)
+      # Find campaign by id
+      all.find { |campaign| (campaign.campaign_id == id.to_s) }
+    end
+
+    def self.find(id_or_web_id)
+      # Campaign finder method
+      all = self.all
+      campaign = self.find_by_id(id_or_web_id.to_s).to_a + self.find_by_web_id(id_or_web_id.to_i).to_a
+      return campaign.blank? ? nil : campaign.first
+    end
+
+    def self.create(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
+      # Create a new campaign
+      # The options hash should be structured as follows:
+      #
+      #   :list_id        = (string)  The ID of the list to send this campaign to.
+      #   :subject        = (string)  The subject of the campaign.
+      #   :from_email     = (string)  The email address this campaign will come from.
+      #   :from_name      = (string)  The name that this campaign will come from.
+      #   :to_email       = (string)  The To: name recipients will see.
+      #   :template_id    = (integer) The ID of the template to use for this campaign (optional).
+      #   :folder_id      = (integer) The ID of the folder to file this campaign in (optional).
+      #   :tracking       = (array)   What to track for this campaign (optional).
+      #   :title          = (string)  Internal title for this campaign (optional).
+      #   :authenticate   = (boolean) Set to true to authenticate campaign (optional).
+      #   :analytics      = (array)   Google analytics tags (optional).
+      #   :auto_footer    = (boolean) Auto-generate the footer (optional)?
+      #   :inline_css     = (boolean) Inline the CSS styles (optional)?
+      #   :generate_text  = (boolean) Auto-generate text from HTML email (optional)?
+      #
+      # Visit http://www.mailchimp.com/api/1.2/campaigncreate.func.php for more information about creating
+      # campaigns via the API.
+      #
+      new(:id => 0).call("campaignCreate", type, options, content, segment_options, type_opts)
+      ## TODO: Return the new campaign with the ID returned from the API
+    end
+
+    def self.templates
+      # Get the templates for this account
+      new(:id => 0).call("campaignTemplates")
+    end
+
+    def add_order(order)
+      # Attach Ecommerce Order Information to a campaign.
+      # The order hash should be structured as follows:
+      #
+      #   :id             = (string)  the order id
+      #   :email_id       = (string)  email id of the subscriber (mc_eid query string)
+      #   :total          = (double)  Show only campaigns with this from_name.
+      #   :shipping       = (string)  *optional - the total paid for shipping fees.
+      #   :tax            = (string)  *optional - the total tax paid.
+      #   :store_id       = (string)  a unique id for the store sending the order in
+      #   :store_name     = (string)  *optional - A readable name for the store, typicaly the hostname.
+      #   :plugin_id      = (string)  the MailChimp-assigned Plugin Id. Using 1214 for the moment.
+      #   :items          = (array)   the individual line items for an order, using the following keys:
+      #
+      #     :line_num      = (integer) *optional - line number of the item on the order
+      #     :product_id    = (integer) internal product id
+      #     :product_name  = (string)  the name for the product_id associated with the item
+      #     :category_id   = (integer) internal id for the (main) category associated with product
+      #     :category_name = (string)  the category name for the category id
+      #     :qty           = (double)  the quantity of items ordered
+      #     :cost          = (double)  the cost of a single item (i.e., not the extended cost of the line)
+      order.merge(:campaign_id => @campaign_id)
+      call("campaignEcommAddOrder", order)
+    end
+
+    def campaign_stats()
+      # Get the stats of a campaign
+      call("campaignStats", @campaign_id)
+    end
+
+    # Get the HTML & text content for a campaign
+    # :for_archive        = (boolean) default true, true returns the content as it would appear in the archive, false returns the raw HTML/text
+    def campaign_content(for_archive = true)
+      # Get the content of a campaign
+      call("campaignContent", @campaign_id, for_archive)
+    end
+
+    def delete_campaign()
+      # Delete a campaign
+      call("campaignDelete", @campaign_id)
+    end
+
+    def replicate_campaign()
+      # Replicate a campaign (returns ID of new campaign)
+      call("campaignReplicate", @campaign_id)
+    end
+
+    def schedule_campaign(time = "#{1.day.from_now}")
+      # Schedule a campaign
+      ## TODO: Add support for A/B Split scheduling
+      call("campaignSchedule", @campaign_id, time)
+    end
+
+    def send_now()
+      # Send a campaign
+      call("campaignSendNow", @campaign_id)
+    end
+
+    # Send a test of a campaign
+    def send_test(emails = {})
+      call("campaignSendTest", @campaign_id, emails)
+    end
+
+    def update(name, value)
+      # Update a campaign
+      call("campaignUpdate", @campaign_id, name, value)
+    end
+
+    def unschedule()
+      # Unschedule a campaign
+      call("campaignUnschedule", @campaign_id)
+    end
+  end
+end
+

data/lib/hominid/helper.rb

@@ -0,0 +1,45 @@
+module Hominid
+
+  class Helper < Base
+    
+    # Helper methods
+    # --------------------------------
+    
+    def self.account_details
+      # Get details for this account.
+      new.call("getAccountDetails")
+    end
+    
+    def self.convert_css_to_inline(html, strip_css = false)
+      # Convert CSS styles to inline styles and (optionally) remove original styles
+      new.call("inlineCss", html, strip_css)
+    end
+    
+    def self.create_folder(name)
+      # Create a new folder to file campaigns in
+      new.call("createFolder", name)
+    end
+    
+    def self.generate_text(type, content)
+      # Have HTML content auto-converted to a text-only format.
+      # The options for text type are:
+      #   'html'      => Expects a string of HTML(default).
+      #   'template'  => Expects an array.
+      #   'url'       => Expects a valid and public URL.
+      #   'cid'       => Expects a campaign ID.
+      #   'tid'       => Expects a template ID.
+      new.call("generateText", type, content)
+    end
+    
+    def self.html_to_text(content)
+      # Convert HTML content to text
+      new.call("generateText", 'html', content)
+    end
+    
+    def self.ping
+      # Ping the Mailchimp API
+      new.call("ping")
+    end
+    
+  end
+end

data/lib/hominid/list.rb

@@ -0,0 +1,150 @@
+module Hominid
+
+  class List < Base
+
+    # List related methods
+    # --------------------------------
+
+    attr_reader :list_id
+    attr_reader :attributes
+
+    def initialize(*args)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      raise StandardError.new('Please provide a List ID.') unless options[:id]
+      @list_id = options.delete(:id)
+      @attributes = options.delete(:attributes)
+      super(options)
+    end
+
+    def self.all
+      # Get all lists for this mailchimp account
+      new(:id => 0).call("lists").to_a.collect { |list| List.new(:id => list.delete('id'), :attributes => list) }
+    end
+
+    def self.find_by_name(name)
+      # Find list by name
+      all.find { |list| list.attributes['name'] =~ /#{name}/ }
+    end
+
+    def self.find_by_web_id(web_id)
+      # Find list by name
+      all.find { |list| (list.attributes['web_id'] == web_id.to_i) }
+    end
+
+    def self.find_by_id(id)
+      # Find list by id
+      all.find { |list| (list.list_id == id.to_s) }
+    end
+
+    def self.find(id_or_web_id)
+      # List finder method
+      all = self.all
+      list = self.find_by_id(id_or_web_id.to_s).to_a + self.find_by_web_id(id_or_web_id.to_i).to_a
+      return list.blank? ? nil : list.first
+    end
+
+    def create_group(group)
+      # Add an interest group to a list
+      call("listInterestGroupAdd", @list_id, group)
+    end
+    alias :interest_group_add :create_group
+
+    def create_tag(tag, name, required = false)
+      # Add a merge tag to a list
+      call("listMergeVarAdd", @list_id, tag, name, required)
+    end
+    alias :merge_var_add :create_tag
+
+    def delete_group(group)
+      # Delete an interest group for a list
+      call("listInterestGroupDel", @list_id, group)
+    end
+    alias :interest_group_del :delete_group
+
+    def delete_tag(tag)
+      # Delete a merge tag and all its members
+      call("listMergeVarDel", @list_id, tag)
+    end
+    alias :merge_var_del :delete_tag
+
+    def groups()
+      # Get the interest groups for a list
+      call("listInterestGroups", @list_id)
+    end
+    alias :interest_groups :groups
+
+
+    def member_info(email)
+      # Get a member of a list
+      call("listMemberInfo", @list_id, email)
+    end
+
+    def members(status = "subscribed", since = "2000-01-01 00:00:00", start = 0, limit = 100)
+      # Get members of a list based on status
+      # Select members based on one of the following statuses:
+      #   'subscribed'
+      #   'unsubscribed'
+      #   'cleaned'
+      #   'updated'
+      #
+      # Select members that have updated their status or profile by providing
+      # a "since" date in the format of YYYY-MM-DD HH:MM:SS
+      call("listMembers", @list_id, status, since, start, limit)
+    end
+
+    def merge_tags()
+      # Get the merge tags for a list
+      call("listMergeVars", @list_id)
+    end
+    alias :merge_vars :merge_tags
+
+    def subscribe(email, options = {})
+      # Subscribe a member to this list
+      merge_tags = clean_merge_tags options[:merge_tags]
+      options = apply_defaults_to({:email_type => "html"}.merge(options))
+      call(
+        "listSubscribe",
+        @list_id,
+        email,
+        merge_tags,
+        *options.values_at(
+          :email_type,
+          :double_opt_in,
+          :update_existing,
+          :replace_interests,
+          :send_welcome
+        )
+      )
+    end
+
+    def subscribe_many(subscribers, options = {})
+      # Subscribe an array of email addresses
+      # subscribers(array) = [{:EMAIL => 'example@email.com', :EMAIL_TYPE => 'html'}]
+      subscribers = subscribers.collect { |subscriber| clean_merge_tags(subscriber) }
+      options = apply_defaults_to({:update_existing => true}.merge(options))
+      call("listBatchSubscribe", @list_id, subscribers, *options.values_at(:double_opt_in, :update_existing, :replace_interests))
+    end
+    alias :batch_subscribe :subscribe_many
+
+    def unsubscribe(current_email, options = {})
+      # Unsubscribe a list member
+      options = apply_defaults_to({:delete_member => true}.merge(options))
+      call("listUnsubscribe", @list_id, current_email, *options.values_at(:delete_member, :send_goodbye, :send_notify))
+    end
+
+    def unsubscribe_many(emails, options = {})
+      # Unsubscribe an array of email addresses
+      # emails(array) = ['first@email.com', 'second@email.com']
+      options = apply_defaults_to({:delete_member => true}.merge(options))
+      call("listBatchUnsubscribe", @list_id, emails, *options.values_at(:delete_member, :send_goodbye, :send_notify))
+    end
+    alias :batch_unsubscribe :unsubscribe_many
+
+    def update_member(current_email, merge_tags = {}, email_type = "html")
+      # Update a member of this list
+      call("listUpdateMember", @list_id, current_email, merge_tags, email_type, true)
+    end
+
+  end
+end
+