reidab-campaign_monitor 1.3.3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Jordan Brock
+
+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.rdoc

@@ -0,0 +1,63 @@
+= campaign_monitor
+
+This RubyGem provides access to the Campaign Monitor API (http://www.campaignmonitor.com/api).
+
+Campaign Monitor recently made some changes to their API.
+
+patientslikeme's fork makes the following changes:
+
+    * host changed from http://app.campaignmonitor.com to http://api.createsend.com
+    * ID values are no longer sent #to_i because they are hex strings
+    * added support for subscribers with custom fields using SOAP API
+    * refactored gemspec to build on github
+    * misc. cleanup and refactoring
+    
+This fork integrates the following additional changes:
+    
+    * updates Subscriber#is_subscribed? to work with the latest API. (from amiel)
+    * adds support for array values in custom_field_hash (from oferlin)
+    * API key cleanup (from yyyc514)
+    * added ability to get fetch lists by id using List#GetDetails or List#[] (from yyyc514)
+    * added support for adding and deleting clients (from yyyc514)
+    * added support for querying CM for countries and timezones (from yyyc514)
+    * added support for creating campaigns (from yyyc514)
+    * general test and api cleanup (from yyyc514)
+
+
+== Pre-requisites
+
+An account with Campaign Monitor and the API Key. Accounts are free and can be created at
+http://www.campaignmonitor.com.
+
+== Resources
+
+=== Install
+gem install patientslikeme-campaign_monitor
+
+=== Git Repository
+http://github.com/patientslikeme/campaign_monitor
+
+
+== Usage
+
+  cm = CampaignMonitor.new # assumes you've set CAMPAIGN_MONITOR_API_KEY in your project
+
+  for client in cm.clients
+    for list in client.lists
+      client.name # => returns the name
+    
+      # modify a subscriber list
+      list.add_subscriber(email, name, custom_fields_hash)
+      list.remove_subscriber(email)
+      list.add_and_resubscribe(email, name, custom_fields_hash)
+    
+      # get subscriber list details
+      subscribers = list.active_subscribers(since_time)
+      unsubscribed = list.unsubscribed(since_time)
+      bounced = list.bounced(since_time)
+    end
+  
+    for campaign in client.campaigns
+  
+    end
+  end

data/Rakefile

@@ -0,0 +1,31 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+# read the contents of the gemspec, eval it, and assign it to 'spec'
+# this lets us maintain all gemspec info in one place. Nice and DRY.
+spec = eval(IO.read("campaign_monitor.gemspec"))
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{spec.name}-#{spec.version}}
+end
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*_test.rb']
+  t.verbose = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+  rd.rdoc_dir = 'doc'
+  rd.options = spec.rdoc_options
+end

data/TODO

@@ -0,0 +1,6 @@
+* Decide on convents about when to raise and when to return true/false
+
+  So far I've kind of taken the stance if we're retrieving a list and there
+  are only two possible failures (APIKey or primary key) to raise if there
+  is an error but for update/save/create operations to return true/false
+  and then let the user probe @object.result for more details

data/campaign_monitor.gemspec

@@ -0,0 +1,53 @@
+Gem::Specification.new do |s|
+  s.platform    = Gem::Platform::RUBY
+  s.name        = 'campaign_monitor'
+  s.version     = "1.3.3"
+  s.summary     = 'Provides access to the Campaign Monitor API.'
+  s.description = <<-EOF
+    A simple wrapper class that provides basic access to the Campaign Monitor API.
+  EOF
+  s.author      = 'Jeremy Weiskotten'
+  s.email       = 'jweiskotten@patientslikeme.com'
+  s.homepage    = 'http://github.com/reidab/campaign_monitor/'
+  s.has_rdoc    = true
+  
+  s.requirements << 'none'
+  s.require_path = 'lib'
+
+  s.add_dependency 'xml-simple', ['>= 1.0.11']
+  s.add_dependency 'soap4r', ['>= 1.5.8']
+ 
+  s.files = [
+      'campaign_monitor.gemspec',
+      'init.rb',
+      'install.rb',
+      'MIT-LICENSE',
+      'Rakefile',
+      'README.rdoc',
+      'TODO',
+      
+      'lib/campaign_monitor.rb',
+      'lib/campaign_monitor/base.rb',
+      'lib/campaign_monitor/misc.rb',
+      'lib/campaign_monitor/campaign.rb',
+      'lib/campaign_monitor/client.rb',
+      'lib/campaign_monitor/helpers.rb',
+      'lib/campaign_monitor/list.rb',
+      'lib/campaign_monitor/result.rb',
+      'lib/campaign_monitor/subscriber.rb',
+      
+      'support/class_enhancements.rb',
+      'support/faster-xml-simple/lib/faster_xml_simple.rb',
+      'support/faster-xml-simple/test/regression_test.rb',
+      'support/faster-xml-simple/test/test_helper.rb',
+      'support/faster-xml-simple/test/xml_simple_comparison_test.rb',
+      
+      'test/campaign_monitor_test.rb',
+      'test/campaign_test.rb',
+      'test/client_test.rb',
+      'test/list_test.rb',
+      'test/test_helper.rb'
+    ]
+
+  s.test_file = 'test/campaign_monitor_test.rb'
+end

data/init.rb

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

data/lib/campaign_monitor.rb

@@ -0,0 +1,270 @@
+require 'rubygems'
+require 'cgi'
+require 'net/http'
+require 'xmlsimple'
+require 'date'
+gem 'soap4r'
+
+require File.join(File.dirname(__FILE__), '../support/class_enhancements.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/helpers.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/misc.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/base.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/client.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/list.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/subscriber.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/result.rb')
+require File.join(File.dirname(__FILE__), 'campaign_monitor/campaign.rb')
+
+# A wrapper class to access the Campaign Monitor API. Written using the wonderful
+# Flickr interface by Scott Raymond as a guide on how to access remote web services
+#
+# For more information on the Campaign Monitor API, visit http://campaignmonitor.com/api
+#
+# Author::    Jordan Brock <jordan@spintech.com.au>
+# Copyright:: Copyright (c) 2006 Jordan Brock <jordan@spintech.com.au>
+# License::   MIT <http://www.opensource.org/licenses/mit-license.php>
+#
+# USAGE:
+#   require 'campaign_monitor'
+#   cm = CampaignMonitor.new(API_KEY)     # creates a CampaignMonitor object
+#                                         # Can set CAMPAIGN_MONITOR_API_KEY in environment.rb
+#   cm.clients                            # Returns an array of clients associated with
+#                                         #   the user account
+#   cm.campaigns(client_id)
+#   cm.lists(client_id)
+#   cm.add_subscriber(list_id, email, name)
+#
+# == CLIENT
+#   client = Client[client_id] # find an existing client
+#   client = Client.new(attributes)
+#   client.Create
+#   client.Delete
+#   client.GetDetail
+#   client.UpdateAccessAndBilling
+#   client.UpdateBasics
+#   client.update # update basics, access, and billing
+#   client.lists # OR
+#   client.GetLists
+#   client.lists.build # to create a new unsaved list for a client
+#   client.campaigns # OR
+#   client.GetCampaigns 
+#
+# == LIST
+#   list = List[list_id] # find an existing list
+#   list = List.new(attributes)
+#   list.Create
+#   list.Delete
+#   list.Update
+#   list.add_subscriber(email, name)
+#   list.remove_subscriber(email)
+#   list.active_subscribers(date)
+#   list.unsubscribed(date)
+#   list.bounced(date)
+#
+# == CAMPAIGN
+#   campaign = Campaign.new(campaign_id)
+#   campaign.clicks
+#   campaign.opens
+#   campaign.bounces
+#   campaign.unsubscribes
+#   campaign.number_recipients
+#   campaign.number_clicks
+#   campaign.number_opens
+#   campaign.number_bounces
+#   campaign.number_unsubscribes
+#
+#
+# == SUBSCRIBER
+#   subscriber = Subscriber.new(email)
+#   subscriber.add(list_id)
+#   subscriber.unsubscribe(list_id)
+#
+# == Data Types
+#   SubscriberBounce
+#   SubscriberClick
+#   SubscriberOpen
+#   SubscriberUnsubscribe
+#   Result
+#
+class CampaignMonitor
+  include CampaignMonitor::Helpers
+  
+  class InvalidAPIKey < StandardError
+  end
+
+  class ApiError < StandardError
+  end
+  
+  attr_reader :api_key, :api_url
+  
+  # Replace this API key with your own (http://www.campaignmonitor.com/api/)
+  def initialize(api_key=CAMPAIGN_MONITOR_API_KEY)
+    @api_key = api_key
+    @api_url = 'http://api.createsend.com/api/api.asmx'
+    CampaignMonitor::Base.client=self
+   end
+
+   # Takes a CampaignMonitor API method name and set of parameters;
+   # returns an XmlSimple object with the response
+  def request(method, params)
+    request_xml=http_get(request_url(method, params))
+    begin
+      response = PARSER.xml_in(request_xml, { 'keeproot' => false,
+        'forcearray' => %w[List Campaign Subscriber Client SubscriberOpen SubscriberUnsubscribe SubscriberClick SubscriberBounce],
+        'noattr' => true })
+      response.delete('d1p1:type')
+      response.delete("d1p1:http://www.w3.org/2001/XMLSchema-instance:type")
+      response
+    # rescue XML::Parser::ParseError
+    rescue XML::Error
+      { "Code" => 500, "Message" => request_xml.split(/\r?\n/).first, "FullError" => request_xml }
+    end
+  end
+
+  # Takes a CampaignMonitor API method name and set of parameters; returns the correct URL for the REST API.
+  def request_url(method, params={})
+    params.merge!('ApiKey' => api_key)
+    
+    query = params.collect do |key, value|
+      "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
+    end.sort * '&'
+    
+    "#{api_url}/#{method}?#{query}"
+  end
+
+  # Does an HTTP GET on a given URL and returns the response body
+  def http_get(url)
+    response=Net::HTTP.get_response(URI.parse(url))
+    response.body.to_s
+  end
+
+  # By overriding the method_missing method, it is possible to easily support all of the methods
+  # available in the API
+  def method_missing(method_id, params = {})
+    puts "  CM: #{method_id} (#{params.inspect})" if $debug
+    res=request(method_id.id2name.gsub(/_/, '.'), params)
+    puts "    returning: #{res.inspect}" if $debug
+    res
+  end
+
+  # Returns an array of Client objects associated with the API Key
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  @clients = @cm.clients
+  #
+  #  for client in @clients
+  #    puts client.name
+  #  end
+  def clients
+    handle_response(User_GetClients()) do |response|
+      response["Client"].collect{|c| Client.new({"ClientID" => c["ClientID"], "CompanyName" => c["Name"]})}
+    end
+  end
+  
+  def new_client
+    Client.new(nil)
+  end
+  
+  def system_date
+    User_GetSystemDate()
+  end
+
+  def parsed_system_date
+    DateTime.strptime(system_date, timestamp_format)
+  end
+  
+  def countries
+    handle_response(User_GetCountries()) do | response |
+      response["string"]
+    end
+  end
+  
+  def timezones
+    handle_response(User_GetTimezones()) do | response |
+      response["string"]
+    end
+  end
+  
+  # Returns an array of Campaign objects associated with the specified Client ID
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  @campaigns = @cm.campaigns(12345)
+  #
+  #  for campaign in @campaigns
+  #    puts campaign.subject
+  #  end
+  def campaigns(client_id)
+    handle_response(Client_GetCampaigns("ClientID" => client_id)) do |response|
+      response["Campaign"].collect{|c| Campaign.new(c) }
+    end
+  end
+
+  # Returns an array of Subscriber Lists for the specified Client ID
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  @lists = @cm.lists(12345)
+  #
+  #  for list in @lists
+  #    puts list.name
+  #  end
+  def lists(client_id)
+    handle_response(Client_GetLists("ClientID" => client_id)) do |response|
+      response["List"].collect{|l| List.new({"ListID" => l["ListID"], "Title" => l["Name"]})}
+    end
+  end
+
+  # A quick method of adding a subscriber to a list. Returns a Result object
+  #
+  # Example
+  #  @cm = CampaignMonitor.new()
+  #  result = @cm.add_subscriber(12345, "ralph.wiggum@simpsons.net", "Ralph Wiggum")
+  #
+  #  if result.succeeded?
+  #    puts "Subscriber Added to List"
+  #  end
+  def add_subscriber(list_id, email, name)
+    Result.new(Subscriber_Add("ListID" => list_id, "Email" => email, "Name" => name))
+  end
+  
+  def using_soap
+    driver = wsdl_driver_factory.create_rpc_driver
+    driver.wiredump_dev = STDERR if $debug
+    response = yield(driver)
+    driver.reset_stream
+    
+    response
+  end
+
+  protected
+
+    def wsdl_driver_factory
+      SOAP::WSDLDriverFactory.new("#{api_url}?WSDL")
+    end
+  
+end
+
+# If libxml is installed, we use the FasterXmlSimple library, that provides most of the functionality of XmlSimple
+# except it uses the xml/libxml library for xml parsing (rather than REXML). 
+# If libxml isn't installed, we just fall back on XmlSimple.
+
+PARSER =
+  begin
+    require 'xml/libxml'
+    # Older version of libxml aren't stable (bus error when requesting attributes that don't exist) so we
+    # have to use a version greater than '0.3.8.2'.
+    raise LoadError unless XML::Parser::VERSION > '0.3.8.2'
+    $:.push(File.join(File.dirname(__FILE__), '..', 'support', 'faster-xml-simple', 'lib'))
+    require 'faster_xml_simple' 
+    p 'Using libxml-ruby'
+    FasterXmlSimple
+  rescue LoadError
+    begin
+      require 'rexml-expansion-fix'
+    rescue LoadError => e
+      p 'Cannot load rexml security patch'
+    end
+    XmlSimple
+  end