mc 0.0.4

data/lib/mc/commands/search.rb

@@ -0,0 +1,21 @@
+desc 'Search campaigns and members'
+command :search do |c|
+  # helper/search-campaigns (string apikey, string query, int offset, string snip_start, string snip_end)
+  c.desc 'Search all campaigns for the specified query terms'
+  c.command :campaigns do |s|
+    s.action do |global,options,args|
+      campaigns = required_argument("You need to include a search argument: mc search campaigns <query terms>", args.join(' '))
+      @output.search @mailchimp_cached.helper_search_members(:query => query)
+    end
+  end
+
+  # helper/search-members (string apikey, string query, string id, int offset)
+  c.desc 'Search account wide or on a specific list using the specified query terms'
+  c.command :members do |s|
+    s.action do |global,options,args|
+      query = required_argument("You need to include a search argument: mc search members <query terms>", args.join(' '))
+      @output.search @mailchimp_cached.helper_search_members(:query => query)
+    end
+  end
+end
+

data/lib/mc/commands/templates.rb

@@ -0,0 +1,11 @@
+desc 'Manage templates within your account'
+
+command :templates do |c|
+  # templates/list (string apikey, struct types, struct filters)
+  c.desc 'Retrieve various templates available in the system'
+  c.command :list do |s|
+    s.action do |global,options,args|
+      @output.standard @mailchimp_cached.templates_list
+    end
+  end
+end

data/lib/mc/commands/users.rb

@@ -0,0 +1,21 @@
+desc 'Users'
+command :users do |c|
+  # users/invite (string apikey, string email, string role, string msg)
+  c.desc 'Invite a user to your account'
+  c.command :invite do |s|
+    s.action do |global,options,args|
+      emails = create_email_struct(options[:email])
+
+      status = @mailchimp.vip_add(:id => id, :emails => emails)
+      puts status
+    end
+  end
+
+  # useres/logins (string apikey)
+  c.desc 'Retrieve the list of active logins.'
+  c.command :logins do |s|
+    s.action do
+      puts @mailchimp_cached.users_logins
+    end
+  end
+end

data/lib/mc/commands/vip.rb

@@ -0,0 +1,51 @@
+desc 'VIPs'
+command :vip do |c|
+  c.desc 'List ID'
+  c.flag :id
+
+  # vip/activity (string apikey)
+  c.desc 'Show all Activity (opens/clicks) for VIPs over the past 10 days'
+  c.command :activity do |s|
+    s.action do
+      @output.standard @mailchimp_cached.vip_activity, :fields => [:email, :action, :title, :timestamp, :url], :reverse => true
+    end
+  end
+
+  # vip/add (string apikey, string id, array emails)
+  c.desc 'Add VIP(s)'
+  c.command :add do |s|
+    s.action do |global,options,args|
+      id = get_required_argument(:id, options[:id], global[:default_list])
+      emails = create_email_struct(required_argument("Need to provide an email address.", args))
+
+      status = @mailchimp.vip_add(:id => id, :emails => emails)
+      if emails.count == status['success_count']
+        puts "Successfully added email(s)!"
+      else
+        @output.errors status
+      end
+    end
+  end
+
+  # vip/del (string apikey, string id, array emails)
+  c.desc 'Remove VIP(s)'
+  c.command :remove do |s|
+    s.action do |global,options,args|
+      id = get_required_argument(:id, options[:id], global[:default_list])
+      emails = create_email_struct(required_argument("Need to provide an email address.", args))
+
+      status = @mailchimp.vip_del(:id => id, :emails => emails)
+      #TODO: create helper method to display success
+      puts status
+      #status["success"] > 0 ? "#{options[:email]} removed!" : "Oops!"
+    end
+  end
+
+  # vip/members (string apikey)
+  c.desc 'List all VIPs'
+  c.command :members do |s|
+    s.action do
+      @output.standard @mailchimp_cached.vip_members, :fields => [:email, :list_name, :member_rating]
+    end
+  end
+end

data/lib/mc/helper.rb

@@ -0,0 +1,62 @@
+module Helper
+  def na(item)
+    if item.nil?
+      return "NA"
+    elsif item.is_a? Float
+      '%.2f' % item
+    else
+      item
+    end
+  end
+
+  def get_required_argument(name, option, global)
+    return option unless option.nil?
+    return global unless global.nil?
+    help_now!("--#{name.to_s} is required")
+  end
+
+  def required_option(name, *options)
+    options.each {|o| return o unless o.nil? or o.empty?}
+    exit_now!("Error: --#{name.to_s} is required")
+  end
+
+  def required_argument(msg, *arguments)
+    arguments.each {|a| return a unless a.nil? or a.empty?}
+    exit_now!(msg)
+  end
+
+  def get_last_campaign_id
+    @mailchimp_cached.campaigns_list(:limit => 1, :sort_field => "create_time")["data"].first["id"]
+  end
+
+  def create_email_struct(emails)
+    struct = []
+    emails.each do |email|
+      struct << {:email => email}
+    end
+
+    return struct
+  end
+
+  def not_implemented
+    raise "This command is not implemented yet."
+  end
+
+  def view_to_print(global, fields, print_options=nil)
+    if global[:raw]
+      # only show the first field and nothing else
+      return fields.first, {:show_index => false}
+    else
+      return fields, print_options
+    end
+  end
+
+  private
+
+  def pad(num, total)
+    padding = ""
+    amount_to_pad = total.to_s.size - num.to_s.size
+    amount_to_pad.times {padding << " "}
+    padding + num.to_s
+  end
+end

data/lib/mc/mailchimp.rb

@@ -0,0 +1,29 @@
+require 'gibbon'
+require 'filecache'
+
+class MailChimp
+  def initialize(apikey, options={})
+    @api = Gibbon::API.new(apikey)
+    @api.throws_exceptions = true
+    @options = options
+
+    @exporter = @api.get_exporter
+  end
+
+  def method_missing(method_name, *args)
+    puts "DEBUG: Calling '#{method_name}(#{args})'..." if @options[:debug]
+    category = method_name.to_s.split('_').first
+    method   = method_name.to_s.split('_')[1..-1].join('_')
+    if category == "export"
+      @exporter.send(method, *args)
+    else
+      if method == 'send'
+        # handle wonk case of 'send' method
+        @api.send(category).send(*args)
+      else
+        # had to change this from .send(method, *args) to .method_missing b/c of gibbon 1.0.3
+        @api.send(category).method_missing(method, *args)
+      end
+    end
+  end
+end

data/lib/mc/mailchimp_cached.rb

@@ -0,0 +1,44 @@
+require 'gibbon'
+require 'filecache'
+require 'digest/sha1'
+
+class MailChimpCached < MailChimp
+  def initialize(apikey, options={})
+    super(apikey, options)
+
+    # configure filecache
+    cache_dir = File.join(File.expand_path(ENV['HOME']), ".mailchimp-cache")
+
+    # expire in one day
+    expiry = 60 * 60 * 24
+
+    @cache = FileCache.new(apikey, cache_dir, expiry)
+    @skip_cache = options[:skip_cache]
+  end
+
+  def cache_value(key, value)
+    puts "cache returns: #{@cache.set(key, value)}"
+  end
+
+  private
+
+  def method_missing(method_name, *args)
+    puts "DEBUG: Calling '#{method_name}(#{args})'..." if @options[:debug]
+    cache_key = Digest::SHA1.hexdigest(method_name.to_s + args.to_s)
+
+    if result = @cache.get(cache_key) and not @skip_cache
+      puts "DEBUG: USING CACHED RESULT" if @options[:debug]
+      return result
+    else
+      category = method_name.to_s.split('_').first
+      method   = method_name.to_s.split('_')[1..-1].join('_')
+
+      throw "error: don't support caching send" if method == 'send'
+
+      result = @api.send(category).method_missing(method, *args)
+      @cache.set(cache_key, result)
+
+      return result
+    end
+  end
+end

data/lib/mc/report.rb

@@ -0,0 +1,140 @@
+module Report
+  class BaseReport
+    def initialize(api)
+      @api = api
+    end
+
+    def run
+      raise NotImplementedError.new("You must implement the run method.")
+    end
+  end
+
+  class CampaignStats < BaseReport
+    def initialize(api, start=0)
+      super(api)
+      @start = start
+    end
+
+    def run
+      last_campaign_sent = @api.campaigns(:filters => {:status => "sent"}, :start => @start, :limit => 1)
+      campaign_data = last_campaign_sent['data'].first
+      campaign_id = campaign_data['id']
+
+      campaign_stats = @api.campaign_stats({:cid => campaign_id})
+      emails_sent = campaign_stats['emails_sent']
+
+      email_domains = @api.campaign_email_domain_performance({:cid => campaign_id})
+
+      puts "Details for #{campaign_data['title']} - #{campaign_data['archive_url']}"
+      puts "==="
+      puts "Sent at #{campaign_data['send_time']}"
+      puts "Last open at #{campaign_stats['last_open']}"
+
+      puts "--"
+      puts "Emails sent: #{emails_sent}"
+      puts "Opens: #{campaign_stats['unique_opens']} (%#{(campaign_stats['unique_opens'].to_f / emails_sent).round(4) * 100})"
+      puts "Users who clicked: #{campaign_stats['users_who_clicked']} (%#{(campaign_stats['users_who_clicked'].to_f / emails_sent).round(4) * 100})"
+      puts "Clicks: #{campaign_stats['unique_clicks']}"
+
+      puts "--"
+      puts "Unsubscribers: #{campaign_stats['unsubscribes']}"
+      puts "Hard/Soft Bounces: #{campaign_stats['hard_bounces']}/#{campaign_stats['soft_bounces']}"
+      puts "Abuse reports: #{campaign_stats['abuse_reports']}"
+
+      puts "--"
+      email_domains.each do |domain|
+        puts "#{domain['emails']} sent to #{domain['domain']} - open/click count: #{domain['opens']}/#{domain['clicks']} - open/click %: #{domain['opens_pct']}/#{domain['clicks_pct']}"
+      end
+
+      puts "--"
+      most_clicked_links(campaign_id).first(20).each do |url,clicks|
+        puts "#{clicks} - #{url[0..70]}"
+      end
+    end
+
+    def most_clicked_links(campaign_id)
+      most_clicked = {}
+
+      url_click_stats = @api.campaign_click_stats({:cid => campaign_id})
+      url_click_stats.each do |stat|
+        most_clicked[stat.first] = stat.last['unique']
+      end
+
+      most_clicked.sort_by {|url,clicks| -clicks}
+    end
+  end
+
+  class TotalClicks < BaseReport
+    def initialize(api, list_id)
+      super(api)
+      @list_id = list_id
+    end
+
+    def run
+      @api.campaigns(:filters => {:list_id => @list_id}, :limit => 25)['data'].each do |campaign|
+        puts "#{campaign['subject']} - #{@api.campaignStats({:cid => campaign['id']})['clicks'].to_i}"
+      end
+    end
+  end
+ 
+  class ArchiveUrls < BaseReport
+    def initialize(api, list_id)
+      super(api)
+      @list_id = list_id
+    end
+
+    def run
+      @api.campaigns(:filters => {:list_id => @list_id}, :limit => 20)['data'].each do |campaign|
+        if campaign['subject'] != nil 
+          puts "<a href=\"#{campaign['archive_url']}\" class=\"link\">#{campaign['subject'].match('\d+')}</a>,"
+        end
+      end
+    end
+  end
+
+  class Zeitgest < BaseReport
+    def initialize(api, list_id, year)
+      super(api)
+      @list_id = list_id
+      @year    = year
+    end
+
+    def run
+      @campaigns = load_campaigns
+      yearly_most_popular
+    end
+
+    def load_campaigns
+      campaigns = []
+
+      @api.campaigns_list(:filters => {:list_id => @list_id}, :limit => 100)['data'].each do |campaign|
+        if campaign['send_time'] != nil && campaign['send_time'].match(/#{@year.to_s}/)
+          campaigns << campaign
+        end
+      end
+
+      return campaigns
+    end
+
+    def yearly_most_popular
+      stats = {}
+      max_rate = 0
+
+      @campaigns.each do |campaign|
+        @api.campaignClickStats(:cid => campaign['id']).each do |item|
+          url, stat = item
+          click_rate = (stat["clicks"] / campaign['emails_sent'].to_f) * 100
+          max_rate = click_rate if click_rate > max_rate
+          stats[url] = [click_rate, campaign['send_time'][5..6]]
+        end
+      end
+
+      normalize = 100 / max_rate
+
+      stats.sort_by { |url, clicks| clicks[0] }.reverse[0..100].each_with_index do |(url, data), index|
+        click_rate, month = data
+        puts "#{index}. #{url} - #{click_rate * normalize} in #{month}"
+      end
+    end
+  end
+end

data/lib/mc/version.rb

@@ -0,0 +1,4 @@
+module MC
+  # have to check const defined for 1.8.7 to avoid warnings
+  VERSION = '0.0.4' unless const_defined?(:VERSION)
+end

data/lib/mc/writer.rb

@@ -0,0 +1,174 @@
+require 'awesome_print'
+require 'table_print'
+
+class ConsoleWriter
+  def initialize(options)
+    @options = options
+    puts "*** DEBUG ON ***" if @options[:debug]
+  end
+
+  def standard(results, options={})
+    redirect_output? results, options
+    as_table results, options
+  end
+
+  def as_hash(results, options={})
+    redirect_output? results, options
+
+    if results.is_a? Hash and results.has_key? 'data'
+      ap results['data'].first, options
+    else
+      ap results, options
+    end
+  end
+
+  def as_table(results, options={})
+    redirect_output? results, options
+
+    results.reverse! if options[:reverse]
+    tp results, options[:fields]
+  end
+
+  def errors(results)
+    puts "Error count: #{results['error_count']}"
+    results['errors'].each do |error|
+      puts error['error']
+    end
+  end
+
+  def flat_hash(hash, k = [])
+    return {k => hash} unless hash.is_a?(Hash)
+    hash.inject({}){ |h, v| h.merge! flat_hash(v[-1], k + [v[0]]) }
+  end
+
+  def as_formatted(results, options={})
+    redirect_output? results, options
+
+    # set default options
+    options[:show_header] ||= true
+    options[:show_index]  ||= false
+    options[:debug]       ||= false
+
+    fields = options[:fields]
+
+    # find the correct staring level in the returned json
+    if results.kind_of? Hash
+      # array of hashes or just a single hash?
+      if results["data"].nil?
+        results = [results]
+      else
+        results = results["data"]
+      end
+    end
+
+    if fields == :all
+      fields = []
+      results.first.each_key {|key| fields << key}
+    end
+
+    results.reverse! if options[:reverse]
+    results = results[0..options[:limit]] if options[:limit]
+
+    puts "Fields: #{[*fields].join(', ')}" unless fields.nil? || !options[:show_header]
+
+    results.to_enum.with_index(1) do |item, index|
+      if options[:debug] || fields.nil?
+        puts "Number of items: #{results.count}"
+        puts "Fields:"
+        item.each do |k,v|
+          if v.kind_of? Hash
+            puts "#{k} ="
+            v.each do |k,v|
+              puts "     #{k} = #{v}"
+            end
+          elsif v.kind_of? Array
+            puts "#{k} ="
+            v.each do |i|
+              if i.kind_of? Hash
+                i.each do |k,v|
+                  puts "     #{k} = #{v}"
+                end
+              else
+                puts "     #{i}"
+              end
+            end
+          else
+            puts "#{k} = #{v}"
+          end
+        end
+        return
+      else
+        values_to_print = []
+        [*fields].each do |field|
+          if field.class == Hash
+            values_to_print << item[field.keys.first.to_s][field.values.first.to_s]
+          else
+            values_to_print << item[field.to_s]
+          end
+        end
+
+        print "#{pad(index, results.count)} - " if options[:show_index]
+        puts  "#{values_to_print.join(' ')}"
+      end
+    end
+  end
+
+  def search(results)
+    redirect_output?(results)
+
+    i = results
+    if i['exact_matches']['total'].to_i == 0 and i['full_search']['total'].to_i == 0
+      exit_now!("No matches found.")
+    end
+
+    members = []
+
+    if i['exact_matches']['total'].to_i > 0
+      puts "#{'='*20} Exact Matches (#{i['exact_matches']['total']}) #{'='*20}"
+
+      i['exact_matches']['members'].each do |member|
+        members << member
+      end
+    elsif i['full_search']['total'].to_i > 0
+      puts "#{'='*26} Matches (#{i['full_search']['total']}) #{'='*26}"
+      i['full_search']['members'].each do |member|
+        members << member
+      end
+    end
+
+    tp members, :email, :id, :member_rating, :status, "VIP?" => {:display_method => :is_gmonkey}
+  end
+
+  private
+
+  def debug(results)
+    puts "#{'*'*50}"
+    puts results
+    puts results.class
+    puts "#{'*'*50}"
+  end
+
+
+  def show_member(m)
+    puts "#{m['id']} - #{m['email']}: Rating=#{m['member_rating']}, List=#{m['list_name']}, VIP?=#{m['is_gmonkey']}"
+  end
+
+  def redirect_output?(results, options={})
+    if @options[:output]
+      case @options[:output].to_sym
+      when :table
+        as_table results, options
+        exit_now!('')
+      when :formatted
+        as_formatted results, options
+        exit_now!('')
+      when :raw
+        puts results
+        exit_now!('')
+      when :awesome, :hash
+        ap results
+        exit_now!('')
+      end
+    end
+  end
+end