monkey_wrench 0.1.0

data/README.mdown

@@ -0,0 +1,18 @@
+# MonkeyWrench
+MonkeyWrench is a rubyesque API for interfacing with [Mailchimp](http://www.mailchimp.com) (or show me some love by registering [via my affiliate link](http://eepurl.com/Ge71)).
+
+## Getting Started
+
+To get started, you need to first connect to the appropriate datacenter with your API key:
+
+    MonkeyWrench::Config.new(:datacenter => "us1", 
+                             :apikey => "your-api-key-goes-here")
+
+From there you've got a rich API for managing Lists and Members. To subscribe a new user to a list simply do the following:
+
+    list = MonkeyWrench::List.find_by_name("My Example List")
+    list.subscribe("foo@bar.com")
+    
+## Further Reading
+
+For more information, [check the documentation](http://rdoc.info/projects/rubypond/monkeywrench)

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rubygems'
+require 'rake'
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = false
+end
+
+task :default => :test

data/lib/monkey_wrench.rb

@@ -0,0 +1,10 @@
+require "httparty"
+base_dir = File.join(File.dirname(__FILE__), "monkey_wrench")
+["base", "config", "hash", "list", "error", "member"].each do |lib|
+  require File.join(base_dir, lib)
+end
+
+begin
+  OpenStruct.class_eval { undef :id, :type }
+rescue NameError
+end

data/lib/monkey_wrench/array.rb

@@ -0,0 +1,9 @@
+require 'cgi'
+module MonkeyWrench
+  module Array
+  end
+end
+
+class Array
+  include MonkeyWrench::Array
+end

data/lib/monkey_wrench/base.rb

@@ -0,0 +1,67 @@
+begin
+  require 'yajl'
+rescue LoadError
+  require 'json'
+end
+require 'ostruct'
+module MonkeyWrench
+  class Base < OpenStruct
+    include HTTParty
+
+    @@apikey = nil
+    @@datacenter = nil
+    
+    class << self
+      def default_options
+        { :output => "json", :apikey=> @@apikey}
+      end
+      
+      def base_uri
+        "http://#{datacenter}.api.mailchimp.com/1.2/"
+      end
+
+      def get(params)
+        response = super(base_uri, :query => params.merge(default_options))
+        handle_errors(response.parsed_response)
+      end
+      
+      def post(params)
+        response = super(base_uri, :query => params.merge(default_options))
+        handle_errors(response.parsed_response)
+      end
+      
+      def handle_errors(objects)
+        return objects unless objects.respond_to?(:has_key?)
+        
+        if objects.has_key?("error")
+          objects.replace({ "error" => MonkeyWrench::Error.new(objects['error'], objects['code']) })
+        elsif objects.has_key?("errors")
+          objects["errors"] = objects["errors"].map do |err|
+            message = err.delete('message')
+            code = err.delete('code')
+            MonkeyWrench::Error.new(message, code, err)
+          end
+        end
+        objects
+      end
+
+      def apikey
+        @@apikey
+      end
+      
+      def datacenter
+        @@datacenter
+      end
+    end
+    
+    private
+      def get(params)
+        self.class.get(params)
+      end
+    
+      def post(params)
+        self.class.post(params)
+      end
+    
+  end
+end

data/lib/monkey_wrench/config.rb

@@ -0,0 +1,34 @@
+require 'yaml'
+module MonkeyWrench
+  class Config < MonkeyWrench::Base
+    # Establishes a connection to the Mailchimp API.
+    #
+    # Can be called with either a path to a file containing credentials, or 
+    # a hash of credentials. The formats of each are:
+    #
+    # File:
+    #   mailchimp:
+    #     datacenter: us1 # Or whatever DC you use
+    #     apikey: your-api-key-goes-here
+    # Hash:
+    #   { :datacenter => "us1", :apikey => "your-api-key-goes-here"}
+    #
+    # @example
+    #     MonkeyWrench::Config.new(:datacenter => "us1", 
+    #                              :apikey => "your-api-key-goes-here")
+    #
+    # @param [String, Hash] credentials accepts either a String pointing to a file
+    # containing the credentials, or a hash of credentials. 
+    def initialize(credentials)
+      if credentials.is_a?(String)
+        config = YAML.load_file(credentials)["mailchimp"]
+        config.collect_kv!{|k,v| [k.to_sym, v]}
+      else
+        config = credentials
+      end
+      @@apikey = config[:apikey]
+      @@datacenter = config[:datacenter]
+      super({})
+    end
+  end
+end

data/lib/monkey_wrench/error.rb

@@ -0,0 +1,104 @@
+module MonkeyWrench
+  class Error < StandardError
+    attr_reader :code
+
+    def initialize(message, code, extra_fields = {}) 
+      super(message)
+      @code = code
+      @extra_fields = extra_fields
+    end
+
+    def type
+      types[@code]
+    end
+
+    def method_missing(sym, *args, &block)
+      return @extra_fields[sym.to_s] if @extra_fields.has_key?(sym.to_s)
+    end
+    
+    def types
+      {
+        -32601 => 'ServerError_MethodUnknown',
+        -32602 => 'ServerError_InvalidParameters',
+        -99 => 'Unknown_Exception',
+        -98 => 'Request_TimedOut',
+        -92 => 'Zend_Uri_Exception',
+        -91 => 'PDOException',
+        -91 => 'Avesta_Db_Exception',
+        -90 => 'XML_RPC2_Exception',
+        -90 => 'XML_RPC2_FaultException',
+        -50 => 'Too_Many_Connections',
+        0 => 'Parse_Exception',
+        100 => 'User_Unknown',
+        101 => 'User_Disabled',
+        102 => 'User_DoesNotExist',
+        103 => 'User_NotApproved',
+        104 => 'Invalid_ApiKey',
+        105 => 'User_UnderMaintenance',
+        120 => 'User_InvalidAction',
+        121 => 'User_MissingEmail',
+        122 => 'User_CannotSendCampaign',
+        123 => 'User_MissingModuleOutbox',
+        124 => 'User_ModuleAlreadyPurchased',
+        125 => 'User_ModuleNotPurchased',
+        126 => 'User_NotEnoughCredit',
+        127 => 'MC_InvalidPayment',
+        200 => 'List_DoesNotExist',
+        210 => 'List_InvalidInterestFieldType',
+        211 => 'List_InvalidOption',
+        212 => 'List_InvalidUnsubMember',
+        213 => 'List_InvalidBounceMember',
+        214 => 'List_AlreadySubscribed',
+        215 => 'List_NotSubscribed',
+        220 => 'List_InvalidImport',
+        221 => 'MC_PastedList_Duplicate',
+        222 => 'MC_PastedList_InvalidImport',
+        230 => 'Email_AlreadySubscribed',
+        231 => 'Email_AlreadyUnsubscribed',
+        232 => 'Email_NotExists',
+        233 => 'Email_NotSubscribed',
+        250 => 'List_MergeFieldRequired',
+        251 => 'List_CannotRemoveEmailMerge',
+        252 => 'List_Merge_InvalidMergeID',
+        253 => 'List_TooManyMergeFields',
+        254 => 'List_InvalidMergeField',
+        270 => 'List_InvalidInterestGroup',
+        271 => 'List_TooManyInterestGroups',
+        300 => 'Campaign_DoesNotExist',
+        301 => 'Campaign_StatsNotAvailable',
+        310 => 'Campaign_InvalidAbsplit',
+        311 => 'Campaign_InvalidContent',
+        312 => 'Campaign_InvalidOption',
+        313 => 'Campaign_InvalidStatus',
+        314 => 'Campaign_NotSaved',
+        315 => 'Campaign_InvalidSegment',
+        316 => 'Campaign_InvalidRss',
+        317 => 'Campaign_InvalidAuto',
+        318 => 'MC_ContentImport_InvalidArchive',
+        330 => 'Invalid_EcommOrder',
+        350 => 'Absplit_UnknownError',
+        351 => 'Absplit_UnknownSplitTest',
+        352 => 'Absplit_UnknownTestType',
+        353 => 'Absplit_UnknownWaitUnit',
+        354 => 'Absplit_UnknownWinnerType',
+        355 => 'Absplit_WinnerNotSelected',
+        500 => 'Invalid_Analytics',
+        501 => 'Invalid_DateTime',
+        502 => 'Invalid_Email',
+        503 => 'Invalid_SendType',
+        504 => 'Invalid_Template',
+        505 => 'Invalid_TrackingOptions',
+        506 => 'Invalid_Options',
+        507 => 'Invalid_Folder',
+        508 => 'Invalid_URL',
+        550 => 'Module_Unknown',
+        551 => 'MonthlyPlan_Unknown',
+        552 => 'Order_TypeUnknown',
+        553 => 'Invalid_PagingLimit',
+        554 => 'Invalid_PagingStart'
+      }
+    end
+  end
+end
+
+ 

data/lib/monkey_wrench/hash.rb

@@ -0,0 +1,69 @@
+require 'cgi'
+module MonkeyWrench
+  module Hash
+ 
+    # Takes a block that returns a [key, value] pair
+    # and builds a new hash based on those pairs
+    # Courtesy of http://snuxoll.com/post/2009/02/13/ruby-better-hashcollect
+    def collect_kv
+      result = {}
+      each do |k,v|
+        new_k, new_v = yield k, v
+        result[new_k] = new_v
+      end
+      result
+    end
+    
+    def collect_kv!(&blk)
+      replace(self.collect_kv(&blk))
+    end
+    
+    def escape_keys!
+      collect_kv!{|k,v| [CGI.escape(k.to_s), v]}
+    end
+    
+    def to_mailchimp(index = nil, parent_name = nil)
+      result = self.collect_kv do |k,v|
+        if v.is_a?(Array) && v.first.is_a?(Hash)
+          i = 0
+          v = v.inject({}) do |acc,hash|
+            acc.merge!(hash.to_mailchimp(i, k))
+            i += 1
+            acc
+          end
+        elsif v.is_a?(Hash)
+          if parent_name
+            v = v.collect_kv do |key,val| 
+              keyname = CGI.escape("#{parent_name.to_s}[#{key.to_s.upcase}]")
+              [keyname, val]
+            end
+          else
+            v = { k => v }.to_mailchimp(nil, k)
+          end
+        elsif v.is_a?(Array)
+          results = {}
+          i = 0
+          v.each do |val|
+            keyname = CGI.escape("#{k}[#{i}]")
+            results[keyname] = val
+            i += 1
+          end
+          v = results
+        end
+        k = k.to_s
+        k = "[#{index}][#{k.upcase}]" if index
+        k = [parent_name, k].join if k != parent_name.to_s
+        [CGI.escape(k), v]
+      end
+      if result.detect{|k,v| v.is_a?(Hash)}
+        result.values.first
+      else
+        result
+      end
+    end
+  end
+end
+
+class Hash
+  include MonkeyWrench::Hash
+end

data/lib/monkey_wrench/list.rb

@@ -0,0 +1,309 @@
+require 'cgi'
+
+module MonkeyWrench
+  class List < MonkeyWrench::Base
+
+    # Finds a given list by name
+    # 
+    # @example
+    #   MonkeyWrench::List.find_by_name("My Example List")
+    #
+    # @param [String] list_name the list name
+    # @return [MonkeyWrench::List] the first list found with a matching name
+    def self.find_by_name(list_name)
+      lists = find_all.detect{|list| list.name == list_name}
+    end
+    
+    # Will compare another list against the current one and return true if 
+    # they are the same (based on list ID)
+    #
+    # @example
+    #   list1 = MonkeyWrench::List.find("0a649eafc3")
+    #   list2 = MonkeyWrench::List.find("9f9d54a0c4")
+    #   list3 = MonkeyWrench::List.find("0a649eafc3") # Same as list1!!
+    #   list1 == list2 # false
+    #   list1 == list3 # true
+    # @param [MonkeyWrench::List] other_list Other list to compare against
+    # @return [Boolean]
+    def ==(other_list)
+      other_list.is_a?(self.class) && self.id == other_list.id
+    end
+
+    # Finds a given list by ID
+    #
+    # @example
+    #   MonkeyWrench::List.find("0a649eafc3")
+    #
+    # @param [String] id the unique Mailchimp list ID
+    # @return [MonkeyWrench::List] the list
+    def self.find(id)
+      new(:id => id)
+    end
+    
+    # Finds all lists
+    #
+    # @example
+    #   MonkeyWrench::List.find_all
+    #
+    # @return [Array<MonkeyWrench::List>] 
+    def self.find_all
+      lists = post({ :method => "lists" }).map do |list|
+        List.new(list)
+      end
+    end
+    class << self
+      alias :all :find_all
+    end
+    
+    # Returns all members for this list
+    #
+    # @example Find all members that have unsubscribed in the last 24 hours:
+    #   MonkeyWrench.members(:status => "unsubscribed",
+    #                        :since => Time.now - 86400)
+    #
+    # @param [Hash] options additional option to include when searching.
+    # @option options [String] :status ('subscribed') Filter the list members by status. Can be one of the following: "subscribed", "unsubscribed", "cleaned", "updated".
+    # @option options [DateTime] :since Return all members whose status has changed or whose profile has changed since this date/time (in GMT).
+    # @option options [Integer] :start (0) For large datasets, the page number to start at.
+    # @option options [Integer] :limit (100) For large datasets, the number of results to return. Upper limit is set at 15000.
+    # @option options [Boolean] :full_details (true) Return full member details and not just email address and timestamp.
+    # @return [Array<MonkeyWrench::Member>] 
+    def members(options = {})
+      if options[:since]
+        options[:since] = options[:since].strftime("%Y-%m-%d %H:%M:%S")
+      end
+      options.merge!(:id => self.id, :method => "listMembers")
+      response = post(options)
+      if options[:full_details]
+        response.map do |response_user|
+          member(response_user["email"])
+        end
+      else
+        response.map do |response_user|
+          MonkeyWrench::Member.new(response_user)
+        end
+      end
+    end 
+
+    # Enumerates over each member and executes the provided block. Will 
+    # automatically page and batch requests for members.
+    #
+    # @example
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   emails = []
+    #   list.each_member do |member|
+    #     emails << member.email
+    #   end
+    #
+    # @param [Proc] &block code to execute for each member
+    def each_member(&block) 
+      page = 0
+      loop do
+        batch = members(:start => page, :limit => 15000)
+        break if batch.empty?
+        batch.each do |member|
+          yield member
+        end
+        page += 1
+      end
+    end
+    
+    # Updates details of list members
+    #
+    # @example Update a single member's email address
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   member = {:email => "foo@bar.com", :new_email => "bar@foo.com"}
+    #   list.update_members(member)
+    #
+    # @example Update multiple members' email addresses
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   members = [{:email => "foo@bar.com", :new_email => "bar@foo.com"},
+    #              {:email => "bob@bar.com", :new_email => "bob@foo.com"}]
+    #   list.update_members(members)
+    #
+    # @param [Hash, Array<Hash>] members details of member(s) to update details 
+    #   of. Members are matched based on the value of :email, to update the 
+    #   email address assign the new address to :new_email. All other field 
+    #   names are lowercase symbols representing the MERGEVAR name in 
+    #   Mailchimp (e.g., FNAME is :fname)
+    # @param [Hash] options additional options when updating members.
+    # @option options [String] :email_type Change the email type preference for the member ('html', 'text', or 'mobile').
+    # @option options [Boolean] :replace_interests (true) replace the interest groups provided (will append interest groups to existing values when false).
+    def update_members(members, options = {})
+      members = members.is_a?(Array) ? members : [members]
+      options.merge!(:id => self.id, :method => "listUpdateMember")
+      members.each do |member|
+        mailchimp_args = {:email_address => member[:email]}
+        member[:email] = member[:new_email]
+        member.delete(:new_email)
+        mailchimp_args.merge!({ :merge_vars => member }.to_mailchimp)
+        post(options.merge(mailchimp_args))
+      end
+    end
+    
+    # Find a member in this list with the given email address
+    #
+    # @example
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   list.member("glenn@rubypond.com")
+    #
+    # @param [String] email members email address
+    # @return [MonkeyWrench::Member]
+    def member(email)
+      response = post(:id => self.id, :method => "listMemberInfo", :email_address => email)
+      if response['error']
+        raise response['error']
+      else
+        MonkeyWrench::Member.new(response)
+      end
+    end
+
+    # Subscribes a new member to the list
+    #
+    # @example Subscribe a new email address
+    #   list.subscribe("foo@bar.com")
+    #
+    # @example Subscribe a new member with extended details
+    #   list.subscribe({:email => "foo@bar.com", :type => :html})
+    #
+    # @example Subscribe multiple new members
+    #   subscribers = [{:email => "foo@bar.com", :type => :html},
+    #                  {:email => "bar@foo.com", :type => :html}]
+    #   list.subscribe(subscribe, :send_welcome => true, :double_optin => false)
+    #
+    # @param [String, Hash, Array<Hash>] contact_details the email address or hash of values for the new member
+    # @param [Hash] opts options when adding new member
+    # @option opts [Boolean] :send_welcome (false) if :double_optin if false and this is 
+    #   true, send the lists 'Welcome Email' to the member(s). Will not send email if 
+    #  updating an existing member.
+    # @option opts [Boolean] :double_optin (true) send an opt-in confirmation email
+    # @option opts [Boolean] :update_existing (false) update members that are already subscribed to the list or to return an error (false returns error)
+    # @option opts [Boolean] :replace_interests (true) replace interest groups or append to existing interest groups (false appends to groups)
+    def subscribe(contact_details, opts = {})
+      if contact_details.is_a?(Array)
+        return subscribe_many(contact_details, opts)
+      else
+        if contact_details.is_a?(Hash)
+          email_address = contact_details.delete(:email)
+          opts = opts.merge(contact_details)
+        else
+          email_address = contact_details
+        end        
+        subscribe_one(email_address, opts)
+        return { :success => 1, :errors => []}
+      end
+    end
+    
+    # Unsubscribes a person (or list of people) from the list
+    #
+    # @example Unsubscribe a single user
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   list.unsubscribe("glenn@rubypond.com", :send_goodbye => true) # Unsubscribe a single person
+    #
+    # @example Unsubscribe a list of users
+    #   emails = ["glenn@rubypond.com", "me@glenngillen.com"]
+    #   list.unsubscribe(emails, :send_goodbye => true) # Unsubscribe multiple people at once
+    #
+    # @param [String, Array<String>] email address(es) of people to unsubscribe.
+    # @param [Hash] opts additional option to include when unsubscribing.
+    # @option opts [Boolean] :delete_member (false) completely delete the member from your list instead of just unsubscribing.
+    # @option opts [Boolean] :send_goodbye (true) send the goodbye email to the email addresses.
+    # @option opts [Boolean] :send_notify (false) send the unsubscribe notification email to the address defined in the list email notification settings.
+    # @return [Hash] contains 2 keys. :success contains the number of successful actions, :error a list of all errors.
+    def unsubscribe(emails, opts = {})
+      emails = [*emails]
+      params = { :method => "listBatchUnsubscribe", 
+                 :id => self.id }
+      params[:delete_member] = opts[:delete_member] if opts.has_key?(:delete_member)
+      params[:send_goodbye] = opts[:send_goodbye] if opts.has_key?(:send_goodbye)
+      params[:send_notify] = opts[:send_notify] if opts.has_key?(:send_notify)
+      params.merge!({ :emails => emails }.to_mailchimp)
+      response = post(params)
+      return { :success => response["success_count"],
+               :errors => response["errors"] }
+    end
+    
+    # Will flag the email(s) as opted-out for all future mailing for this list
+    #
+    # @example Opt-out a single user
+    #   list = MonkeyWrench::List.find("0a649eafc3")
+    #   list.opt_out("glenn@rubypond.com") # Opt-out a single person
+    #
+    # @example Opt-out a list of users
+    #   emails = ["glenn@rubypond.com", "me@glenngillen.com"]
+    #   list.opt_out(emails) # Opt-out multiple people at once
+    #
+    # @param [String, Array<String>] email address(es) of people to opt-out.
+    # @return [Hash] contains 2 keys. :success contains the number of successful actions, :error a list of all errors.
+    def opt_out(emails)
+      emails = [*emails]      
+      subscribe(emails.map{|email| { :email => email }})
+      unsubscribe(emails, :send_goodbye => false, :send_notify => false)
+    end
+  
+    private
+      def self.reserved_keys
+        [:email, :type, :double_optin, :update_existing, :replace_interests, 
+         :send_welcome, :emails, :send_notify, :send_goodbye, :delete_member]
+      end
+      
+      def subscribe_many(subscribers, opts = {})
+        if opts[:send_welcome]
+          subscribe_one_at_a_time(subscribers, opts)
+        else
+          subscribe_in_batches(subscribers, opts)
+        end
+      end
+
+      def subscribe_in_batches(subscribers, opts)
+        cumulative_response = { :success => 0, :errors => [] }
+        i = 0
+        while i < subscribers.size
+          response = subscribe_one_batch(subscribers[i..i+9], opts)
+          cumulative_response[:success] += response['success_count']
+          cumulative_response[:errors] += response['errors']
+          i += 10
+        end
+        cumulative_response
+      end
+
+      def subscribe_one_batch(subscribers, opts)
+        params = { :id => self.id, :method => "listBatchSubscribe" }
+        params[:double_optin] = opts[:double_optin] if opts.has_key?(:double_optin)
+        params[:update_existing] = opts[:update_existing] if opts.has_key?(:update_existing)
+        params[:replace_interests] = opts[:replace_interests] if opts.has_key?(:replace_interests)
+        params.merge!({ :batch => subscribers }.to_mailchimp)
+        post(params)
+      end
+
+      def subscribe_one_at_a_time(subscribers, opts)
+        cumulative_response = { :success => 0, :errors => [] }
+        subscribers.each do |subscriber|
+          params = opts.merge(subscriber)
+          params.delete(:email)
+          if subscribe_one(subscriber[:email], params) == true
+            cumulative_response[:success] += 1
+          else
+            cumulative_response[:errors] << response["error"]
+          end
+        end
+        cumulative_response
+      end
+
+      def subscribe_one(email_address, opts = {})
+        params = {
+                  :type => opts.delete(:type),
+                  :double_optin => opts.delete(:double_optin),
+                  :update_existing => opts.delete(:update_existing),
+                  :replace_interests => opts.delete(:replace_interests),
+                  :send_welcome => opts.delete(:send_welcome),
+                  :email => email_address
+                 }
+        params.reject!{ |k,v| v.nil? }
+        merge_vars = { :merge_vars => opts }.to_mailchimp
+        params.merge!(merge_vars)
+        params.merge!(:method => "listSubscribe", :id => self.id)
+        post(params)
+      end
+  end
+end