malechimp 0.0.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+spec/config.yml

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in malechimp.gemspec
+gemspec

data/README.md

@@ -0,0 +1,19 @@
+# MaleChimp
+
+The MailChimp API leaves a lot to be desired for modern application development. This gem provides very basic functionality to add users to a mail list:
+
+```ruby
+joe = MaleChimp::Subscriber.new do |s|
+  s.first_name = 'Joe'
+  s.last_name = 'Plumber'
+  s.email = 'joe@plumber.com'
+  s.fields['last_logged_in_at'] = Time.now
+  s.fields['occupation'] = "Plumber"
+end
+
+Chimp = MaleChimp.new(ENV['MAIL_CHIMP_API_KEY'])
+
+Chimp.list('The Awesome List').subscribe(joe)
+```
+
+Consider this an ugly hack on top of an ugly RPC API, but we run integration tests on this nightly to make sure the API is in working order.

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+
+desc "Copy over configuration files needed to run integration specs"
+task :setup do
+  cp 'spec/config.yml.sample', 'spec/config.yml'
+  puts "Be sure to add your MailChimp API key to spec/config.yml"
+end

data/lib/malechimp.rb

@@ -0,0 +1,54 @@
+require "malechimp/version"
+require 'xmlrpc/client'
+
+module MaleChimp
+  module API
+    VERSION = "1.3".freeze
+    URL = "http://api.mailchimp.com/#{API::VERSION}/".freeze
+  end
+
+  autoload :List,       'malechimp/list'
+  autoload :Subscriber, 'malechimp/subscriber'
+  autoload :Exception,  'malechimp/exception'
+  autoload :Utils,      'malechimp/utils'
+
+  class Base
+    attr_reader :url, :api_key
+
+    # Try to grab the API key out of env and use the default end-point URL
+    def initialize(api_key, url=API::URL)
+      @api_key, @url = api_key, url
+    end
+
+    # Returns all of the mailing lists in Chimp.
+    def lists
+      # In MailChimps infinite wisdom, they implemented REST inside of RPC, so you see stupid stuff like the .data root key.
+      @lists ||= call('lists')['data'].map do |list|
+        List.new(self, list)
+      end
+    end
+
+    # Find a list by name.
+    def list(name)
+      lists.find{ |l| l.name == name }
+    end
+
+    # Zie oh so wunderful API shinannigans
+    def server
+      @server ||= XMLRPC::Client.new2(url)
+    end
+
+  protected
+    # This is a stupid way of trying to make calls to MailChimps RPC api (Really poopy & crappy)
+    def call(*args)
+      begin
+        args = args.insert(1, api_key) # gotta shove the API key in there
+        puts "Calling with #{args.map{|arg| "#{arg.inspect}" }.join(', ')}"
+        server.call(*args)
+      rescue XMLRPC::FaultException => ex
+        puts "XMLRPC Fault #{ex.faultCode}: #{ex.faultString}"
+        raise Exception.lookup(ex.faultCode) || ex
+      end
+    end
+  end
+end

data/lib/malechimp/exception.rb

@@ -0,0 +1,46 @@
+# Error mappings from http://www.mailchimp.com/api/rtfm/exceptions.field.php
+# This is NOT a comprehensive list errors from the API
+module MaleChimp
+  module Exception
+    # Exception hierarchy for good ol' MaleChimp
+    MaleChimpError = Class.new(StandardError)
+      AuthorizationError = Class.new(MaleChimpError)
+      ListError = Class.new(MaleChimpError)
+        ListInvalidInterestFieldType = Class.new(ListError)
+        ListInvalidOption = Class.new(ListError)
+        ListInvalidUnsubMember = Class.new(ListError)
+        ListInvalidBounceMember = Class.new(ListError)
+        ListAlreadySubscribed = Class.new(ListError)
+        ListNotSubscribed = Class.new(ListError)
+        ListInvalidImport = Class.new(ListError)
+      EmailError = Class.new(MaleChimpError)
+        EmailAlreadySubscribed = Class.new(EmailError)
+        EmailAlreadyUnsubscribed = Class.new(EmailError)
+        EmailNotExists = Class.new(EmailError)
+        EmailNotSubscribed = Class.new(EmailError)
+    
+    # Map our fancy exception hierarchy to MaleChimps XML RPC fault codes
+    FAULT_CODE_MAPPING = {
+      210	=> ListInvalidInterestFieldType,
+      211	=> ListInvalidOption,
+      212	=> ListInvalidUnsubMember,
+      213	=> ListInvalidBounceMember,
+      214	=> ListAlreadySubscribed,
+      215	=> ListNotSubscribed,
+      220	=> ListInvalidImport,
+      230	=> EmailAlreadySubscribed,
+      231	=> EmailAlreadyUnsubscribed,
+      232	=> EmailNotExists,
+      233	=> EmailNotSubscribed
+    }
+    
+    def self.lookup(err)
+      if err.respond_to?(:faultCode)
+        code = err.faultCode.to_i
+      else
+        code = err.to_i
+      end
+      FAULT_CODE_MAPPING[code]
+    end
+  end
+end

data/lib/malechimp/list.rb

@@ -0,0 +1,89 @@
+module MaleChimp
+  class List
+    DEFAULT_MAIL_FORMAT = 'html'
+    
+    attr_accessor :base
+    attr_reader :size, :list_id, :name, :created_at
+    
+    # The construct will return
+    # [{
+    #   "name"=>"New Feature Newsletter (APITEST)", 
+    #   "date_created"=>"2008-12-12 03:09:17", 
+    #   "member_count"=>7.0, 
+    #   "unsubscribe_count"=>4.0, 
+    #   "id"=>"5757f43cda", 
+    #   "cleaned_count"=>2.0, 
+    #   "web_id"=>17191
+    # }]
+      
+    def initialize(base, opts={})
+      @base = base
+      @name = opts['name']
+      @created_at = opts['created_at'] || opts['date_created']
+      @size = opts['member_count'] || opts['size']
+      @list_id = opts['id'] || opts['list_id']
+    end
+    
+    def subscribe(user, opts={})
+      opts = {:email_type => DEFAULT_MAIL_FORMAT, :double_optin => false, :update_existing => false, :replace_interests => true, :send_welcome => false}.merge(opts)
+      
+      email_type = opts[:email_type]
+      double_optin = opts[:double_optin]
+      update_existing = opts[:update_existing]
+      replace_interests = opts[:replace_interests]
+      send_welcome = opts[:send_welcome]
+
+      # listSubscribe(string email_address, array merge_vars, string email_type, boolean double_optin, boolean update_existing, boolean replace_interests)
+      call('listSubscribe', user.email, user.merge_fields, DEFAULT_MAIL_FORMAT, double_optin, update_existing, replace_interests, send_welcome)
+    end
+    
+    def unsubscribe(user, opts={})
+      opts = {:destroy => false, :send_goodbye => false, :send_notify => false}.merge(opts)
+
+      destroy = opts[:destroy]
+      send_goodbye = opts[:send_goodbye]
+      send_notify = opts[:send_notify]
+
+      surpress_faults Exception::ListNotSubscribed, Exception::EmailNotExists do
+        call('listUnsubscribe', user.email, destroy, send_goodbye, send_notify)
+      end
+    end
+    
+    def update(user, opts={})
+      opts = {:email_type => DEFAULT_MAIL_FORMAT, :replace_interests => true}.merge(opts)
+
+      email_type = opts[:email_type]
+      replace_interests = opts[:replace_interests]
+      
+      call('listUpdateMember', user.email, user.merge_fields, email_type, replace_interests)
+    end
+    
+    def subscriber(email)
+      call('listMemberInfo', email)
+    end
+    
+    def subscribers
+      # listMembers(string apikey, string id, string status, integer since, integer start, integer limit)
+      # returns [{"timestamp"=>"2008-12-12 03:24:05", "email"=>"jeff@jeffvyduna.com"} ...]
+      call('listMembers').map do |s|
+        Subscriber.new(s)
+      end
+    end
+    
+  protected
+    # Curry these puppies some more! Woo yeah! XML RPC IS AWESOME!
+    def call(*args)
+      args = args.insert(1, @list_id) # Gotta shove the list ID in there
+      @base.send(:call, *args)
+    end
+    
+    # Run a method and surpress certain acceptable errors.
+    def surpress_faults(*faults, &block)
+      begin
+        yield block
+      rescue XMLRPC::FaultException => ex
+        faults.include?(Exception.lookup(ex.faultCode)) ? true : raise
+      end
+    end
+  end
+end

data/lib/malechimp/subscriber.rb

@@ -0,0 +1,59 @@
+module MaleChimp
+  class Subscriber
+    DEFAULT_FIELDS = %w(first_name last_name email id)
+    MERGE_FIELD_SIZE = 10 # Another bullshit constraint imposed by MaleChimp
+    
+    attr_accessor *DEFAULT_FIELDS
+    attr_accessor :fields
+    
+    # Map these default fields out into the function
+    DEFAULT_FIELDS.each do |field|
+      eval(%{
+        def #{field}
+          @fields['#{field}']
+        end
+        
+        def #{field}=(val)
+          @fields['#{field}'] = val
+        end
+      })
+    end
+    
+    def initialize(fields={})
+      # Setup our default fields hash
+      @fields = DEFAULT_FIELDS.inject({}) do |h,f|
+        h[f] = '' # Default values to be blank
+        h         # Gotta yield this for inject to work
+      end
+      @fields.merge!(fields)
+      yield self if block_given?
+    end
+    
+    # Guess what guys? Chimp wants all upper case field names and
+    # no spaces for merge fields. Fine, we'll give 'em that!
+    def merge_fields
+      fields.inject({}) do |hash, field|
+        key, value = encode_merge_field(field)
+        hash[key] = value
+        hash
+      end
+    end
+    
+  private
+    # Chimp complains if non-ascii chars.
+    def encode_merge_field_value(val)
+      val.to_s.gsub(/[^\x00-\x7F]/n,'')
+    end
+    
+    # Replaces spaces with an underline and truncate
+    def encode_merge_field_name(key)
+      key.upcase.gsub(/\s/, '_')[0...MERGE_FIELD_SIZE]
+    end
+    
+    # Clean up the merge field so that chimp and Ruby RPC don't cry
+    def encode_merge_field(field)
+      key, val = field
+      [ encode_merge_field_name(key), encode_merge_field_value(val) ]
+    end
+  end
+end

data/lib/malechimp/test_helper.rb

@@ -0,0 +1,16 @@
+require 'yaml'
+require 'ostruct'
+
+module MaleChimp
+  module TestHelper
+    # Load the MailChimp API key
+    def self.config
+      @config ||= begin
+        OpenStruct.new(YAML.load(File.read(File.expand_path('../../../spec/config.yml', __FILE__))))
+      rescue Errno::ENOENT
+        puts "Oops! You didn't run `rake setup` to configure your integration test settings."
+        exit 1
+      end
+    end
+  end
+end

data/lib/malechimp/utils/utils.rb

@@ -0,0 +1,45 @@
+# Random utilities and scripts for MaleChimp
+require 'rubygems'
+require 'hpricot'
+require 'open-uri'
+require 'pp'
+
+module MaleChimp
+  module Utils
+    module Exceptions
+      EXCEPTIONS_SPEC = 'http://www.mailchimp.com/api/rtfm/exceptions.field.php'
+      
+      class << self
+        # Screen scrapes the faults from the Chimp API
+        def faults_list(url=EXCEPTIONS_SPEC)
+          doc = Hpricot(open(url))
+          # change the CSS class on links
+          (doc/"table tr").inject({}) do |faults, row|
+            code, error = (row/"td").map{ |cell| cell.inner_text }
+            if code =~ /[0-9-]+/
+              faults[code.to_i] = error
+            end
+            faults
+          end
+        end
+        
+        DEFAULT_GROUP = 'General'
+        
+        def group_faults(faults)
+          groups = { DEFAULT_GROUP => [] }
+          faults.map do |code, message|
+            group, error = message.split(/_/, 2)
+            
+            group         ||= DEFAULT_GROUP
+            groups[group] ||= []
+            
+            groups[group] << [code, error]
+          end
+          groups
+        end
+      end
+    end
+  end
+end
+
+include MaleChimp::Utils

data/lib/malechimp/version.rb

@@ -0,0 +1,3 @@
+module MaleChimp
+  VERSION = "0.0.1"
+end

data/malechimp.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "malechimp/version"
+
+Gem::Specification.new do |s|
+  s.name        = "malechimp"
+  s.version     = MaleChimp::VERSION
+  s.authors     = ["Brad Gessler"]
+  s.email       = ["brad@bradgessler.com"]
+  s.homepage    = ""
+  s.summary     = %q{A crappy MailChimp API integration for a crappy API}
+  s.description = %q{MailChimps XMP RPC API is insanity if you're a modern developer. This provides a more OO approach to dealing with the MCAPI.}
+
+  s.rubyforge_project = "malechimp"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  # specify any dependencies here; for example:
+  s.add_development_dependency "rspec"
+end

data/spec/config.yml.sample

@@ -0,0 +1,8 @@
+# API key for your MailChimp account.
+api_key: <your api key here>
+
+# You have to log-in to MailChimp and create this list.
+list: <my list here>
+
+# A junky email address will do.
+email: john.deer@something.com

data/spec/malechimp_spec.rb

@@ -0,0 +1,126 @@
+require 'spec_helper'
+
+describe MaleChimp::Subscriber do
+  before(:each) do
+    @subscriber = MaleChimp::Subscriber.new do |s|
+      s.first_name = 'Brad'
+      s.last_name = 'Gessler'
+      s.email = MaleChimp::TestHelper.config.email
+      s.fields['last_logged_in_at'] = Time.now
+      s.fields['crap'] = "?hey"
+    end
+  end
+  
+  it "should have fields" do
+    @subscriber.should respond_to(:fields)
+    @subscriber.fields.values.should include('Gessler', 'Brad', MaleChimp::TestHelper.config.email)
+  end
+  
+  it "should have first_name" do
+    @subscriber.should respond_to(:first_name)
+    @subscriber.first_name.should eql('Brad')
+  end
+  
+  it "should have last_name" do
+    @subscriber.should respond_to(:last_name)
+    @subscriber.last_name.should eql('Gessler')
+  end
+  
+  it "should have email" do
+    @subscriber.should respond_to(:email)
+    @subscriber.email.should eql(MaleChimp::TestHelper.config.email)
+  end
+  
+  it "should have merge_fields" do
+    @subscriber.should respond_to(:merge_fields)
+  end
+  
+  it "should upcase and strip spaces from merge fields" do
+    @subscriber.merge_fields.keys.should include('FIRST_NAME', 'LAST_NAME', 'EMAIL')
+  end
+  
+  it "should truncate long merge fields to 10 characters" do
+    @subscriber.merge_fields.should include('LAST_LOGGE')
+  end
+end
+
+describe MaleChimp::List, "initialization" do
+  before(:all) do
+    @chimp = MaleChimp::Base.new(MaleChimp::TestHelper.config.api_key)
+    @subscriber = MaleChimp::Subscriber.new do |s|
+      s.first_name = 'Brad'
+      s.last_name = 'Gessler'
+      s.email = MaleChimp::TestHelper.config.email
+    end
+    @list = @chimp.list(MaleChimp::TestHelper.config.list)
+  end
+  
+  it "should add new user to list" do
+    @list.subscribe(@subscriber)
+  end
+  
+  it "should update user on list" do
+    @subscriber.email = MaleChimp::TestHelper.config.email
+    @list.update(@subscriber)
+  end
+  
+  it "should remove user from list" do
+    @list.unsubscribe(@subscriber)
+  end
+
+  it "should remove user from list silently" do
+    @list.subscribe(@subscriber)
+    @list.unsubscribe(@subscriber, :send_goodbye => false)
+  end
+end
+
+describe MaleChimp::List do
+  before(:all) do
+    @chimp = MaleChimp::Base.new(MaleChimp::TestHelper.config.api_key)
+    @hash = {
+      "name" => "New Feature Newsletter (APITEST)", 
+      "date_created" => "2008-12-12 03:09:17", 
+      "member_count" => 7.0, 
+      "unsubscribe_count" => 4.0, 
+      "id" =>"5757f43cda", 
+      "cleaned_count" => 2.0, 
+      "web_id" => 17191
+    }
+  end
+  
+  it "should initialize with arguments from MaleChimp::Base#list" do
+    MaleChimp::List.new(@chimp, @hash).should be_instance_of(MaleChimp::List)
+  end
+  
+  it "should have created_at" do
+    MaleChimp::List.new(@chimp, @hash).created_at.should eql(@hash['date_created'])
+  end
+  
+  it "should have size" do
+    MaleChimp::List.new(@chimp, @hash).size.should eql(@hash['member_count'])
+  end
+  
+  it "should have name" do
+    MaleChimp::List.new(@chimp, @hash).name.should eql(@hash['name'])
+  end
+  
+  it "should have list_id" do
+    MaleChimp::List.new(@chimp, @hash).list_id.should eql(@hash['id'])
+  end
+end
+
+describe MaleChimp::Base do
+  before(:all) do
+    @chimp = MaleChimp::Base.new(MaleChimp::TestHelper.config.api_key)
+  end
+  
+  it "should have lists" do
+    @chimp.should respond_to(:lists)
+    @lists = @chimp.lists
+    @lists.first.should be_instance_of(MaleChimp::List)
+  end
+  
+  it "should have server" do
+    @chimp.should respond_to(:server)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper.rb"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'rubygems'
+require 'malechimp'
+require 'malechimp/test_helper'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: malechimp
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Brad Gessler
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70308222140160 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70308222140160
+description: MailChimps XMP RPC API is insanity if you're a modern developer. This
+  provides a more OO approach to dealing with the MCAPI.
+email:
+- brad@bradgessler.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- README.md
+- Rakefile
+- lib/malechimp.rb
+- lib/malechimp/exception.rb
+- lib/malechimp/list.rb
+- lib/malechimp/subscriber.rb
+- lib/malechimp/test_helper.rb
+- lib/malechimp/utils/utils.rb
+- lib/malechimp/version.rb
+- malechimp.gemspec
+- spec/config.yml.sample
+- spec/malechimp_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: malechimp
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: A crappy MailChimp API integration for a crappy API
+test_files:
+- spec/config.yml.sample
+- spec/malechimp_spec.rb
+- spec/spec_helper.rb
+has_rdoc: