Empact-hominid 1.1.12

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 [Brian Getting]
+
+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.

data/README.textile

@@ -0,0 +1,77 @@
+h1. Hominid
+
+Hominid is a Ruby gem for interacting with the "Mailchimp API":http://www.mailchimp.com/api/1.2/.
+
+h2. Installation
+
+Install the gem:
+
+<pre><code>gem sources -a http://gems.github.com
+sudo gem install bgetting-hominid</code></pre>
+
+In your @environment.rb@ file:
+
+<pre><code>config.gem "bgetting-hominid", :lib => 'hominid', :source => "http://gems.github.com"</code></pre>
+
+You can also install Hominid as a Rails plugin:
+
+<pre><code>script/plugin install git://github.com/bgetting/hominid.git</code></pre>
+
+h2. Setup
+
+Hominid expects to find a config file at @/config/hominid.yml@ in a Rails application, but you can also pass a hash of config options when creating a new Hominid object (thanks to "ron":http://github.com/ron).
+
+You will also need to create a Mailchimp account to get your API key (available at "http://admin.mailchimp.com/account/api/":http://admin.mailchimp.com/account/api/) to configure a Hominid object. 
+
+h2. Example
+
+To interact with the Mailchimp API, simply create a new Hominid object:
+
+<pre><code>@hominid = Hominid.new</code></pre>
+
+_or_
+
+<pre><code>@hominid = Hominid.new({:username => 'USERNAME', :password => 'PASSWORD', :api_key => 'API_KEY', :send_goodbye => false, :send_notify => false, :double_opt => false})</code></pre>
+
+You will need to have the @list ID@ of the mailing list you want to work with. You can find the @list ID@ of a list by:
+
+<pre><code>
+def find_list_id(list_name)
+  mailing_lists = @hominid.lists
+  unless mailing_lists.nil?
+    @list_id = mailing_lists.find {|list| list["name"] == list_name}["id"]
+  end
+end
+</code></pre>
+
+To subscribe:
+
+<pre><code>@hominid.subscribe(@list_id, "email@example.com", {:FNAME => 'Bob', :LNAME => 'Smith'}, 'html')</code></pre>
+
+To unsubscribe:
+
+<pre><code>@hominid.unsubscribe(@list_id, "email@example.com")</code></pre>
+
+To update a member:
+
+<pre><code>@hominid.subscribe(@list_id, "email@example.com", {:FNAME => 'Robert', :EMAIL => 'another@example.com'}, 'html', true)</code></pre>
+
+_or_
+
+<pre><code>@hominid.update_member(@list_id, "email@example.com", {:FNAME => 'Robert', :EMAIL => 'another@example.com'})</code></pre>
+
+Campaign methods are also supported. You can get all the campaigns for a particular list by:
+
+<pre><code>@hominid.campaigns(@list_id)</code></pre>
+
+Leave the @@list_id@ out and it will return all the campaigns for your Mailchimp account.
+
+h2. Other Stuff
+
+For the most part, this whole thing was an attempt to optimize the acts_as_mailchimp plugin, and incorporates all the great work from "C.G. Brown":http://www.projectlocker.com/ and "Kelly Mahan":http://digimedia.com/, as well as "Matthew Carlson":http://mandarinsoda.com/, whose plugin inspired nearly all of this work. Recently, "ron":http://github.com/ron and "netguru":http://github.com/netguru have also provided useful changes as well.
+
+I encourage anyone using this gem to please fork it, improve it, and send me a pull request. I typically only use this gem in a minimal capacity, primarily for just managing whether or not a user is signed up for a mailing list. I do not intend to continue maintaining the "Acts As Mailchimp":http://github.com/bgetting/acts_as_mailchimp in the future, since I personally prefer to just use the Hominid gem.
+
+So please, help us to improve this gem!
+
+Copyright (c) 2009 Brian Getting, released under the MIT license.

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "hominid"
+    s.summary = "Hominid is a Rails GemPlugin for interacting with the Mailchimp API"
+    s.email = "brian@terra-firma-design.com"
+    s.homepage = "http://github.com/bgetting/hominid"
+    s.description = "Hominid is a Rails GemPlugin for interacting with the Mailchimp API"
+    s.authors = ["Brian Getting"]
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the hominid plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the hominid plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Hominid'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 1
+:minor: 1
+:patch: 12

data/hominid.gemspec

@@ -0,0 +1,52 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{hominid}
+  s.version = "1.1.12"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Getting"]
+  s.date = %q{2009-09-18}
+  s.description = %q{Hominid is a Rails GemPlugin for interacting with the Mailchimp API}
+  s.email = %q{brian@terra-firma-design.com}
+  s.extra_rdoc_files = [
+    "README.textile"
+  ]
+  s.files = [
+    "MIT-LICENSE",
+     "README.textile",
+     "Rakefile",
+     "VERSION.yml",
+     "hominid.gemspec",
+     "hominid.yml.tpl",
+     "init.rb",
+     "install.rb",
+     "lib/hominid.rb",
+     "rails/init.rb",
+     "spec/hominid_spec.rb",
+     "spec/spec_helper.rb",
+     "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/bgetting/hominid}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Hominid is a Rails GemPlugin for interacting with the Mailchimp API}
+  s.test_files = [
+    "spec/hominid_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/hominid.yml.tpl

@@ -0,0 +1,24 @@
+# Get your API key at http://admin.mailchimp.com/account/api/
+development:
+  username:
+  password: 
+  api_key: 
+  send_goodbye: false
+  send_notify: false
+  double_opt: false
+
+test:
+  username:
+  password:
+  api_key: 
+  send_goodbye: false
+  send_notify: false
+  double_opt: false
+
+production:
+  username:
+  password:
+  api_key: 
+  send_goodbye: false
+  send_notify: false
+  double_opt: false

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/install.rb

@@ -0,0 +1,4 @@
+require 'fileutils'
+monkeyBrains = File.dirname(__FILE__) + '/../../../config/hominid.yml'
+FileUtils.cp File.dirname(__FILE__) + '/hominid.yml.tpl', monkeyBrains unless File.exist?(monkeyBrains)
+puts IO.read(File.join(File.dirname(__FILE__), 'README'))

data/lib/hominid.rb

@@ -0,0 +1,263 @@
+require 'xmlrpc/client'
+
+class HominidError < RuntimeError
+  def initialize(message)
+    super(message)
+  end
+end
+
+class HominidCommunicationError < HominidError
+  def initialize(message)
+    super(message)
+  end
+end
+
+class Hominid
+  
+  # MailChimp API Documentation: http://www.mailchimp.com/api/1.2/
+  MAILCHIMP_API = "http://api.mailchimp.com/1.2/"
+
+  def initialize(config = nil)
+    load_monkey_brains(config)
+    @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+  end
+
+  def load_monkey_brains(config)
+    config = YAML.load(File.open("#{RAILS_ROOT}/config/hominid.yml"))[RAILS_ENV].symbolize_keys unless config
+    @chimpUsername  = config[:username].to_s
+    @chimpPassword  = config[:password].to_s
+    @api_key        = config[:api_key]
+    @send_goodbye   = config[:send_goodbye]
+    @send_notify    = config[:send_notify]
+    @double_opt     = config[:double_opt] || false
+  end
+  
+  ## Security related methods
+  
+  def add_api_key
+    begin
+      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+      @chimpApi.call("apikeyAdd", @chimpUsername, @chimpPassword, @api_key)
+    rescue
+      false
+    end
+  end
+  
+  def expire_api_key
+    begin
+      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+      @chimpApi.call("apikeyExpire", @chimpUsername, @chimpPassword, @api_key)
+    rescue
+      false
+    end
+  end
+  
+  def api_keys(include_expired = false)
+    begin
+      @chimpApi ||= XMLRPC::Client.new2(MAILCHIMP_API)
+      @api_keys = @chimpApi.call("apikeys", @chimpUsername, @chimpPassword, include_expired)
+    rescue
+      return nil
+    end
+  end
+  
+  ## Campaign related methods
+  
+  def campaign_content(campaign_id)
+    # Get the content of a campaign
+    @content = call("campaignContent", campaign_id)
+  end
+  
+  def campaigns(filters = {}, start = 0, limit = 50)
+    # Get the campaigns for this account
+    # API Version 1.2 requires that filters be sent as a hash
+    # Available options for the filters hash are:
+    #
+    #   :campaign_id    = (string)  The ID of the campaign you wish to return. 
+    #   :list_id        = (string)  Show only campaigns with this list_id. 
+    #   :folder_id      = (integer) Show only campaigns from this folder.
+    #   :from_name      = (string)  Show only campaigns with this from_name.
+    #   :from_email     = (string)  Show only campaigns with this from_email.
+    #   :title          = (string)  Show only campaigns with this title.
+    #   :subject        = (string)  Show only campaigns with this subject.
+    #   :sedtime_start  = (string)  Show campaigns sent after YYYY-MM-DD HH:mm:ss.
+    #   :sendtime_end   = (string)  Show campaigns sent before YYYY-MM-DD HH:mm:ss.
+    #   :subject        = (boolean) Filter by exact values, or search within content for filter values.
+    @campaigns = call("campaigns", filters, start, limit)
+  end
+
+  # Attach Ecommerce Order Information to a Campaign.
+  # The order hash should be structured as follows: 
+  #
+  #   :id             = (string)  the order id 
+  #   :campaign_id    = (string)  the campaign id to track the order (mc_cid query string). 
+  #   :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)
+  def campaign_ecomm_add_order(order)
+    @campaign = call("campaignEcommAddOrder", order)
+  end
+
+  def create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
+    # Create a new campaign
+    @campaign = call("campaignCreate", type, options, content, segment_options, type_opts)
+  end
+  
+  def delete_campaign(campaign_id)
+    # Delete a campaign
+    @campaign = call("campaignDelete", campaign_id)
+  end
+  
+  def replicate_campaign(campaign_id)
+    # Replicate a campaign (returns ID of new campaign)
+    @campaign = call("campaignReplicate", campaign_id)
+  end
+  
+  def schedule_campaign(campaign_id, 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(campaign_id)
+    # Send a campaign
+    call("campaignSendNow", campaign_id)
+  end
+  
+  def send_test(campaign_id, emails = {})
+    # Send a test of a campaign
+    call("campaignSendTest", campaign_id, emails)
+  end
+  
+  def templates
+    # Get the templates
+    @templates = call("campaignTemplates", @api_key)
+  end
+  
+  def update_campaign(campaign_id, name, value)
+    # Update a campaign
+    call("campaignUpdate", campaign_id, name, value)
+  end
+  
+  def unschedule_campaign(campaign_id)
+    # Unschedule a campaign
+    call("campaignUnschedule", campaign_id)
+  end
+  
+  ## Helper methods
+  
+  def html_to_text(content)
+    # Convert HTML content to text
+    @html_to_text = call("generateText", 'html', content)
+  end
+  
+  def convert_css_to_inline(html, strip_css = false)
+    # Convert CSS styles to inline styles and (optionally) remove original styles
+    @html_to_text = call("inlineCss", html, strip_css)
+  end
+  
+  ## List related methods
+  
+  def lists
+    # Get all of the lists for this mailchimp account
+    @lists = call("lists", @api_key)
+  end
+  
+  def create_group(list_id, group)
+    # Add an interest group to a list
+    call("listInterestGroupAdd", list_id, group)
+  end
+  
+  def create_tag(list_id, tag, name, required = false)
+    # Add a merge tag to a list
+    call("listMergeVarAdd", list_id, tag, name, required)
+  end
+  
+  def delete_group(list_id, group)
+    # Delete an interest group for a list
+    call("listInterestGroupDel", list_id, group)
+  end
+  
+  def delete_tag(list_id, tag)
+    # Delete a merge tag and all its members
+    call("listMergeVarDel", list_id, tag)
+  end
+  
+  def groups(list_id)
+    # Get the interest groups for a list
+    @groups = call("listInterestGroups", list_id)
+  end
+  
+  def member(list_id, email)
+    # Get a member of a list
+    @member = call("listMemberInfo", list_id, email)
+  end
+  
+  def members(list_id, 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
+    # 
+    @members = call("listMembers", list_id, status, since, start, limit)
+  end
+  
+  def merge_tags(list_id)
+    # Get the merge tags for a list
+    @merge_tags = call("listMergeVars", list_id)
+  end
+  
+  def subscribe(list_id, email, user_info = {}, email_type = "html", update_existing = true, replace_interests = true, double_opt_in = false)
+    # Subscribe a member
+    call("listSubscribe", list_id, email, user_info, email_type, double_opt_in || @double_opt, update_existing, replace_interests)
+  end
+  
+  def subscribe_many(list_id, subscribers)
+    # Subscribe a batch of members
+    # subscribers = {:EMAIL => 'example@email.com', :EMAIL_TYPE => 'html'} 
+    call("listBatchSubscribe", list_id, subscribers, @double_opt, true)
+  end
+  
+  def unsubscribe(list_id, current_email)
+    # Unsubscribe a list member
+    call("listUnsubscribe", list_id, current_email, true, @send_goodbye, @send_notify)
+  end
+  
+  def unsubscribe_many(list_id, emails)
+    # Unsubscribe an array of email addresses
+    # emails = ['first@email.com', 'second@email.com'] 
+    call("listBatchUnsubscribe", list_id, emails, true, @send_goodbye, @send_notify)
+  end
+  
+  def update_member(list_id, current_email, user_info = {}, email_type = "")
+    # Update a member of this list
+    call("listUpdateMember", list_id, current_email, user_info, email_type, true)
+  end
+  
+  protected
+  def call(method, *args)
+    @chimpApi.call(method, @api_key, *args)
+  rescue XMLRPC::FaultException => error
+    raise HominidError.new(error.message)
+  rescue Exception => error
+    raise HominidCommunicationError.new(error.message)
+  end
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require 'hominid'

data/spec/hominid_spec.rb

@@ -0,0 +1,21 @@
+require 'spec/spec_helper'
+
+describe Hominid do
+  before do
+    api_key = ENV['MAIL_CHIMP_API_KEY']
+    raise "You must set the MAIL_CHIMP_API_KEY environment variable to test" if api_key.empty?
+    @hominid = Hominid.new(:api_key => api_key)
+    @list_id = ENV['MAIL_CHIMP_TEST_LIST_ID']
+    raise "You must set the MAIL_CHIMP_TEST_LIST_ID environment variable to test" if @list_id.empty?
+  end
+  
+  describe "#subscribe" do
+    context "when not supplying a double-opt-in argument" do
+      it "should not blow up" do
+        proc {
+          @hominid.subscribe(@list_id, Faker::Internet.email)
+        }.should_not raise_error
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'faker'
+require 'lib/hominid'

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: Empact-hominid
+version: !ruby/object:Gem::Version 
+  version: 1.1.12
+platform: ruby
+authors: 
+- Brian Getting
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-18 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Hominid is a Rails GemPlugin for interacting with the Mailchimp API
+email: brian@terra-firma-design.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.textile
+files: 
+- MIT-LICENSE
+- README.textile
+- Rakefile
+- VERSION.yml
+- hominid.gemspec
+- hominid.yml.tpl
+- init.rb
+- install.rb
+- lib/hominid.rb
+- rails/init.rb
+- spec/hominid_spec.rb
+- spec/spec_helper.rb
+- uninstall.rb
+has_rdoc: false
+homepage: http://github.com/bgetting/hominid
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Hominid is a Rails GemPlugin for interacting with the Mailchimp API
+test_files: 
+- spec/hominid_spec.rb
+- spec/spec_helper.rb