chimpactions 0.0.0 → 0.0.4

data/app/views/chimpactions/new.html.erb

@@ -0,0 +1,4 @@
+<section>
+<h1>Create a Chimpaction : </h1>
+<%= render :partial => 'form'%>
+</section>

data/app/views/chimpactions/webhooks.html.erb

@@ -0,0 +1,26 @@
+<style>
+.ca_list {list-style:none;padding:0px;}
+</style>
+<div style="font-size:1.2em; color:green;"><%= flash[:notice] if flash[:notice] %></div>
+<ul class="ca_list">
+  <% @lists.each do |list|%>
+  <li><%= list.name%> ( ID : <%= list.id %> )
+    <% if list.webhook? == false %> 
+      <%=link_to "Add Webhook", {:action => 'add_webhook', :id => list.web_id }%>
+    <% else %>
+      <%=link_to "REMOVE Webhook", {:action => 'delete_webhook', :id => list.web_id }%>
+    <%end%>
+  </li>
+  <%end%>
+</ul>
+
+<div style="margin-top:25px;"> Remember !  : in order to do something here, your <%= Chimpactions.registered_class_name %> class must define :
+  <pre> 
+    ...
+    def receive_webhook(post_from_mailchimp)
+      // do something with the MailChimp POST data here
+    end
+    ...
+  </pre>
+  
+</div>

data/chimpactions.gemspec

@@ -9,13 +9,18 @@ Gem::Specification.new do |s|
   s.authors     = ["Peter Bonnell"]
   s.email       = ["gems@circuitllc.com"]
   s.homepage    = ""
-  s.summary     = %q{Chimpactions allows for simple management of subscribers on MailChimp lists}
-  s.description = %q{coming soon....IN DEVELOPMENT AS OF 4/21/2011}
+  s.summary     = %q{chimpactions provides a quick way to move subscribers from one MailChimp list to another.}
+  s.description = %q{chimpactions  }
 
   s.rubyforge_project = "chimpactions"
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.files = Dir["{app,lib,config}/**/*"] + ["MIT-LICENSE", "Rakefile", "Gemfile", "README.textile","chimpactions.gemspec"]
+  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"]
+  s.add_dependency('gibbon', '>= 0.1.5')
+
+  s.post_install_message = %[
+chimpactions has been installed.
+]
 end

data/config/routes.rb

@@ -0,0 +1,8 @@
+ Rails.application.routes.draw do |map|
+   resources :chimpactions, :except => [:show]
+   match 'chimpactions/webhooks', :to => 'chimpactions#webhooks'
+   match 'chimpactions/delete_webhook/:id', :to => 'chimpactions#delete_webhook'
+   match 'chimpactions/add_webhook/:id', :to => 'chimpactions#add_webhook'
+   match 'chimpactions/receive', :to => 'chimpacitons#receive', :as => :webhook
+   match 'chimpactions/index', :to =>  'chimpactions#index'
+ end

data/lib/chimpactions.rb

@@ -1,3 +1,211 @@
+# Holds MailChimp account level information
+# Should set up wit an initializer.
+#require 'active_support'
+require "railtie" if defined?(Rails)
 module Chimpactions
-  # Your code goes here...
-end
+  # ruby wrapper gem for the MailChimp API
+  # https://github.com/amro/gibbon
+#extend ActiveSupport::Autoload 
+  require 'gibbon'
+  require 'chimpactions/engine'# if defined?(Rails)
+  autoload :List, 'chimpactions/list'
+  autoload :Subscriber, 'chimpactions/subscriber'
+  autoload :Utility, 'chimpactions/utility'
+  autoload :Action, 'chimpactions/action'
+  require 'chimpactions/exception'
+  autoload :Setup, 'chimpactions/setup' 
+  autoload :ListNotifier, 'chimpactions/notifier' 
+
+  # Obersver pattern untility class attribute.
+  mattr_accessor :observers
+  @@observers = []
+  
+  # Observer pattern untility.  
+  def self.add_observer(observer)
+    @@observers << observer
+  end
+  
+  # Observer pattern notify untility. 
+  def self.notify_observers(mod)
+    @@observers.each do |o|
+      o.update(mod)
+    end
+  end
+  
+  # Ensure the module has an observer for communicating with List objects.
+  add_observer Chimpactions::ListNotifier.new 
+  
+# BELOW ATTRIBUTES SET IN INSTALLED INITIALIZER
+# => try rake chimpactions:install for full option initilaizer
+
+  # ALL merge variables from anywhere in your MailChimp account
+  mattr_accessor :merge_map
+  @@merge_map = Hash.new
+  
+  # Your MailChimp API KEY
+  mattr_accessor :mailchimp_api_key # your MailChimp API key
+  @@mailchimp_api_key = "your_mailchimp_api_key"
+  
+  # Your MailChimp SES key
+  mattr_accessor :mailchimp_ses_key # your MailChimp ses key
+  @@mailchimp_ses_key = "your_mailchimp_ses_key"
+  
+  # When a class includes Chimpactions::Subscriber, it is registered here
+  mattr_accessor :registered_classes
+  @@registered_classes = Array.new
+
+  # Require the user to reply to the MailChimp system before adding to list.
+  mattr_accessor :default_double_optin
+  @@default_double_optin = false
+  
+  #Have MailChimp send the "Welcome" email for the list immediately on subscribing.
+  mattr_accessor :default_send_welcome
+  @@default_send_welcome = true
+
+  # The default email type when subscribing
+  mattr_accessor :default_email_type
+  @@default_email_type = 'html'
+  
+  # Udpate existing subscriber (to prevent already subscribed error)
+  mattr_accessor :default_update_existing
+  @@default_update_existing = true
+# END INITIALIZER
+
+  mattr_accessor :actions
+  @@actions = Array.new
+
+  # the gibbon API wrapper object for communication with MailChimp servers
+  mattr_accessor :socket
+  
+  def initialize(*atts)
+    super(*atts)
+    puts "**** CA INITIALIZED! ************"
+  end
+  
+  # Assign a local class to the Chimpactions module.
+  # @param [Object] The local object to inherit Chimpactions::Subscriber methods.
+  # - Must respond_to? 'email'
+  # - For methods defined in the Chimpactions merge_map
+  # -- can to respond_to? each method
+  # -- if it does not, Chimpactions will not send the merge variable or value.
+  def self.for(klass_name)
+    klass =  Kernel.const_get(klass_name.to_s.capitalize).new
+    raise Chimpactions::SetupError.new("The #{klass.name} class MUST at least respond to 'email' !") if !klass.respond_to?(:email)
+    Kernel.const_get(klass_name.to_s.capitalize).send(:include, Chimpactions::Subscriber)
+    @@registered_classes << klass if !@@registered_classes.include? klass
+  end
+
+  # # Change the MailChimp used by the system.
+  # Notifies all list objects and reloads the available lists from the new account.
+  # @param [String] A new API key
+  def self.change_account(new_api_key)
+    self.mailchimp_api_key = new_api_key
+    self.socket = Gibbon::API.new(self.mailchimp_api_key)
+    notify_observers self
+    self.available_lists(true)
+  end
+
+  # The registered class
+  # @return [ClassName]
+  def self.registered_class
+    self.registered_classes[0]
+  end
+  
+  
+  def self.registered_class_name
+    self.registered_classes[0].class.name
+  end
+  # Default setup for Chimpactions. Run rails generate chimpactions_install to create
+  # a fresh initializer with configuration options.
+  def self.setup(config)
+   # puts config
+    if config['mailchimp_api_key'] == 'your_mailchimp_api_key' || config['local_model'] == 'YourLocalModel'
+      raise Chimpactions::SetupError.new("You must customize initializers/chimpactions.yml.")
+    end
+ #   klass = Kernel.cont_get(config['local_model'].to_s.capitalize)
+#    @@registered_classes << klass if !@@registered_classes.include? klass
+    self.for(config['local_model'])
+    self.mailchimp_api_key = config['mailchimp_api_key']
+    self.merge_map = config['merge_map']
+    self.mailchimp_ses_key = config['mailchimp_ses_key']
+    self.socket = Gibbon::API.new(self.mailchimp_api_key)
+    case config['action_store']
+    when :yml
+      if !config['actions'].blank?
+        config['actions'].each do |action|
+          self.actions << Chimpactions::Action.new(action)
+        end
+      end
+    when :active_record
+      Chimpaction.all.each do |action|
+        self.actions << Chimpactions::Action.new(action)
+      end
+    end
+  end
+
+  # Queries your MailChimp account for available lists.
+  # @return [Hash] ChimpActions::List objects available in your account.
+  #TODO: What if there are an unmanageable (50+) number of lists? Paginate?
+  def self.available_lists(force=false)
+    if force
+      @available_lists = load_lists.map{|raw_list| Chimpactions::List.new(raw_list)}
+    else
+      @available_lists ||= load_lists.map{|raw_list| Chimpactions::List.new(raw_list)}
+    end
+  end
+  
+  # Query the Mailchimp server for lists in this account
+  # # @return [Hash] Data for the query
+  def self.load_lists
+    # send the query
+    response = socket.lists
+    if !response['error']
+      response['data']
+    else
+      raise MailChimpError.new("#{response['error']} (#{response['code']})")
+    end
+  end
+  
+  # Searches the MailChimp list hash by id, web_id, name
+  # @param [String, Fixnum, Chimpactions::List] list
+  # @return [Chimpactions::List] The Chimpactions List object
+  def self.list(list)
+    case list.class.name
+      when "Chimpactions::List"
+        #if it's a List, just send it back...
+        return_list = [list]
+      when "String"
+        # The List.name , id, or web_id ?
+        return_list = Chimpactions.available_lists.select{|l| l.id == list}
+        return_list = Chimpactions.available_lists.select{|l| l.web_id == list.to_i} if return_list.empty?
+        return_list = Chimpactions.available_lists.select{|l| l.name == list} if return_list.empty?
+      when "Fixnum"
+        return_list = Chimpactions.available_lists.select{|l| l.web_id == list.to_i}
+      else 
+        return_list = []
+    end
+    raise Chimpactions::NotFoundError.new("Could not locate #{list} in your account. ") if return_list.empty?
+    return_list[0]
+  end
+  
+  # Find a list by any list attribute
+  # @param [Hash] :attribute => 'value'
+  # @return Chimpactions::List object
+  def self.find_list(params)
+    available_lists.find{|list| list.method(:params[0].to_s).call == params[1]}
+  end
+
+  # Utility for a hash of lists keyed by name in your MailChimp account.
+  # @return [Hash] Lists available in your MailChimp account, keyed by name. 
+  def self.lists_by_name
+     available_lists.sort{|a,b| a.name <=> b.name}
+  end
+  
+  # Utility for a hash of lists keyed by ID.
+  # @return [Hash] Lists available in your MailChimp account, keyed by id
+  def self.list_ids
+    available_lists.sort{|a,b| a.id <=> b.id}
+  end
+  
+  
+end

data/lib/chimpactions/action.rb

@@ -0,0 +1,73 @@
+module Chimpactions
+  # Defines a single step to take given a set of conditions.
+  class Action
+    
+    #The Chimpaction::Subscriber method to execute for this action.
+    attr_accessor :action
+    #The Chimpactions::List object to excute the action on.
+    attr_accessor :list
+    attr_accessor :whenn
+    attr_accessor :is
+    attr_accessor :value 
+    
+    # @params [String,String,Subscriber,String] {:action, :list, :method, :comparitor, :value}Subscriber method name, = || != || < || >, Subscriber Object, value to test against
+    def initialize(params)
+      if params.class.name == "Hash"
+        params.each_pair do |key,val|
+          self.send(key.to_s.dup << "=", val)
+        end
+      elsif params.class.name == "Chimpaction"
+        ini_ar(params)
+      end
+    end
+    
+    def ini_ar(ar)
+        attribs = %W[action list whenn is value]
+        attribs.each do |attrib|
+          val = ar.send(attrib)
+          self.send(attrib.to_s.dup << "=", val)
+        end
+    end
+    
+    def execute(subscriber)
+      if perform?(subscriber)
+        puts "subscriber.#{action}(\"#{list}\")"
+        eval "subscriber.#{action}(\"#{list}\")"
+      end
+    end
+    
+    # Check the Object attributes against the specified logic.
+    # @param [String,String,Subscriber,String] Subscriber method name, = || != || < || >, Subscriber Object, value to test against
+    def perform?(subscriber)
+    #  puts "#{is}"
+      if  is.eql?("=")
+        is = '==' 
+      end
+     # puts "#{is}"
+      value = cast_value(self.value)
+      value = "\"#{value}\"" if value.class.name == "String"
+    #  puts "*** CHECKING : subscriber.#{whenn} #{is} #{value}"
+      eval "subscriber.#{whenn} #{is} #{value}"
+    end
+    
+    # Utility for casting a String to a 'best guess' Type
+    # @param [Object]
+    # @return [String, Integer, TrueClass, FalseClass]
+    def cast_value(val)
+      raise ArgumentError.new("Your value is not a String! (it's a #{val.class})") if val.class != String && val.class != TrueClass && val.class != FalseClass
+      
+      if (Float val rescue false)
+        Float val
+      elsif (Integer val rescue false)
+        Integer val
+      elsif val =~ /^true$/i || val == true
+        true
+      elsif val =~ /^false$/i || val == false
+        false
+      else
+        val
+      end
+    end
+    
+  end #Action
+end # module

data/lib/chimpactions/engine.rb

@@ -0,0 +1,21 @@
+require "chimpactions"
+require "rails"
+
+module Chimpactions
+ class Engine < Rails::Engine
+    initializer "engine.configure_rails_initialization" do
+      if File.exists?("#{Rails.root}/config/chimpactions.yml") 
+        setup_hash = YAML.load_file("#{Rails.root}/config/chimpactions.yml")
+        model_test =  Kernel.const_get(setup_hash['local_model'].to_s.capitalize) rescue false 
+        if model_test != false
+          Chimpactions.setup(setup_hash)
+          Kernel.const_get(Chimpactions.registered_class_name.to_s.capitalize).send(:include, Chimpactions::Subscriber)
+        else
+          raise Chimpactions::SetupError.new("The #{setup_hash['local_model'].to_s.capitalize} class was not found!")
+        end
+      else 
+        
+      end
+    end
+ end
+end

data/lib/chimpactions/exception.rb

@@ -0,0 +1,14 @@
+module Chimpactions
+    # A Chimpactions specific ArgumentError.
+    class ArgumentError < ArgumentError; end
+    # For an empty result from a MailChimp request.
+    class NotFoundError < StandardError; end
+    # A setting Chimpactions needs is missing or malformed. 
+    class SetupError < RuntimeError; end
+    # Low level error in the MailChimp connection (gibbon).
+    class ConnectionError < IOError; end
+    # Bad API key.
+    class AuthError < ConnectionError; end
+    # An error from the MAilChimp API
+    class MailChimpError < ConnectionError; end
+end

data/lib/chimpactions/list.rb

@@ -0,0 +1,113 @@
+module Chimpactions
+  # The List class does all kinds of things with your MailChimp lists.
+  class List
+    include Chimpactions::Utility
+    
+    cattr_reader :socket
+    # The system-wide single socket to the MailChimp mothership.
+    @@socket = Chimpactions.socket
+    
+    # Receiver for Observer pattern.
+    # Sets the class level socket to the current Chimpactions module socket.
+    def self.new_socket
+      @@socket = Chimpactions.socket
+    end
+    
+    # @return [List::Stats]
+    attr_reader :stats
+  
+    # Create a new List object
+    # @param [Hash] raw MailChimp API data return see Chimpactions::Subscriber
+    def initialize(raw)
+      @raw = raw
+      @stats = Stats.new(@raw.delete('stats'))
+      self
+    end
+    
+    #The raw list data.
+    #@return [Hash]
+    def data
+      @raw
+    end
+
+  # MC API v1.3
+    # def listMergeVarAdd(string apikey, string id, string tag, string name, array options)
+    #   #Add a new merge tag to a given list
+    # end
+    # 
+    # def listMergeVarDel(string apikey, string id, string tag)
+    # end
+    # 
+    # def listMergeVars(string apikey, string id)
+    #   #Get the list of merge tags for a given list, including their name, tag, and required setting 
+    # end
+    # 
+    # def listWebhookAdd(string apikey, string id, string url, array actions, array sources)
+    # actions : 
+      #subscribe	optional - as subscribes occur, defaults to true
+      #boolean	unsubscribe	optional - as subscribes occur, defaults to true
+      #boolean	profile	optional - as profile updates occur, defaults to true
+      #boolean	cleaned	optional - as emails are cleaned from the list, defaults to true
+      #boolean	upemail	optiona 
+    #   #Add a new Webhook URL for the given list
+    # end
+    # 
+    # def listWebhookDel(string apikey, string id, string url)
+    #   #Delete an existing Webhook URL from a given list
+    # end
+    # 
+    # def listWebhooks(string apikey, string id)
+    #   #Return the Webhooks configured for the given list 
+    # end
+  # END MC API
+
+    #The available merge varaibles for the List.
+    def merge_vars
+      @merge_vars ||= @@socket.listMergeVars(:id => id)
+    end
+    
+    # Checks if there are ANY webhooks for this list
+    # @return [boolean]
+    def webhook?
+      @@socket.listWebhooks(:id => id).empty? ? false : true
+    end
+    
+    # Retrieves webhooks for this List
+    # @return [Hash, false]
+    def webhooks
+      @@socket.listWebhooks(:id => id)
+    end
+  
+    # Sets a webhook for this List
+    # @param [Hash] _REQUIRED_ : :url => 'a valid url'
+    # @return [true, Hash] true if ok, otherwise an error hash
+    def set_webhook(opts)
+      @@socket.listWebhookAdd({:id => id}.merge(opts) ) == "true"
+    end
+    
+    # removes the specified url webhook for this List
+    # @param [Hash] _REQUIRED_ : :url => 'a valid, currently used url'
+    # @return [true, Hash] true if ok, otherwise an error hash
+    def remove_webhook(opts)
+      @@socket.listWebhookDel({:id => id}.merge(opts) ) == "true"
+    end
+    
+    # The Stats class is a simple wrapper for statistics about the List.
+    # <code> my_list.stats.subscriber_total #=> 243 </code>
+    class Stats
+      include Chimpactions::Utility
+    
+      def initialize(raw)
+        @raw = raw
+        self
+      end   
+      
+      #The raw data array of statistic info.
+      def data
+        @raw
+      end
+    end #Stats
+    
+  end #List
+  
+end #Chimpactions