exacttarget 0.1.2 → 0.1.3

data/Gemfile

@@ -6,9 +6,10 @@ source "http://rubygems.org"
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "shoulda", ">= 0"
+  gem "shoulda", ">= 2.11.3"
   gem "bundler", "~> 1.0.0"
   gem "jeweler", "~> 1.6.0"
-  gem "rcov", ">= 0"
+  gem "rcov", ">= 0.9.9"
   gem "nokogiri", ">= 1.4.4"
+  gem "yard", ">= 0.6.8"
 end

data/Gemfile.lock

@@ -10,6 +10,7 @@ GEM
     rake (0.8.7)
     rcov (0.9.9)
     shoulda (2.11.3)
+    yard (0.6.8)
 
 PLATFORMS
   ruby
@@ -18,5 +19,6 @@ DEPENDENCIES
   bundler (~> 1.0.0)
   jeweler (~> 1.6.0)
   nokogiri (>= 1.4.4)
-  rcov
-  shoulda
+  rcov (>= 0.9.9)
+  shoulda (>= 2.11.3)
+  yard (>= 0.6.8)

data/README.rdoc

@@ -21,6 +21,6 @@ See LICENSE.txt for further details.
 
 == Support
 
-API documentaiton will be available soon. But until then,
-email all bugs, concerns, etc. to matt.simpson@alextom.com.
+Provided through RubyDoc:
+* http://rubydoc.info/github/msimpson/exacttarget/master/frames
 

data/Rakefile

@@ -41,3 +41,12 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+task :push do
+  system "yardoc"
+  system "git add ."
+  system "rake gemspec:generate"
+  system "git add ."
+  system "git commit -a"
+  system "rake git:release"
+end

data/VERSION

@@ -1 +1 @@
-0.1.2
+0.1.3

data/exacttarget.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{exacttarget}
-  s.version = "0.1.2"
+  s.version = "0.1.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Matthew Simpson"]
-  s.date = %q{2011-05-08}
+  s.date = %q{2011-05-15}
   s.description = %q{ExactTarget is a client system for communicating with the ExactTarget email system. The client supports the most up-to-date XML API and is capable of uploading email pastes, images and retrieving lists of subscribers, emails and more.}
   s.email = %q{matt.simpson@alextom.com}
   s.extra_rdoc_files = [
@@ -26,11 +26,16 @@ Gem::Specification.new do |s|
     "VERSION",
     "exacttarget.gemspec",
     "lib/exacttarget.rb",
-    "lib/exacttarget/client.rb",
     "lib/exacttarget/email.rb",
+    "lib/exacttarget/group.rb",
     "lib/exacttarget/image.rb",
+    "lib/exacttarget/job.rb",
+    "lib/exacttarget/list.rb",
     "lib/exacttarget/templates/email.xml.erb",
+    "lib/exacttarget/templates/group.xml.erb",
     "lib/exacttarget/templates/image.xml.erb",
+    "lib/exacttarget/templates/job.xml.erb",
+    "lib/exacttarget/templates/list.xml.erb",
     "lib/exacttarget/templates/main.xml.erb"
   ]
   s.homepage = %q{http://github.com/msimpson/exacttarget}
@@ -44,24 +49,27 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<shoulda>, [">= 2.11.3"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.6.0"])
-      s.add_development_dependency(%q<rcov>, [">= 0"])
+      s.add_development_dependency(%q<rcov>, [">= 0.9.9"])
       s.add_development_dependency(%q<nokogiri>, [">= 1.4.4"])
+      s.add_development_dependency(%q<yard>, [">= 0.6.8"])
     else
-      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<shoulda>, [">= 2.11.3"])
       s.add_dependency(%q<bundler>, ["~> 1.0.0"])
       s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
-      s.add_dependency(%q<rcov>, [">= 0"])
+      s.add_dependency(%q<rcov>, [">= 0.9.9"])
       s.add_dependency(%q<nokogiri>, [">= 1.4.4"])
+      s.add_dependency(%q<yard>, [">= 0.6.8"])
     end
   else
-    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<shoulda>, [">= 2.11.3"])
     s.add_dependency(%q<bundler>, ["~> 1.0.0"])
     s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
-    s.add_dependency(%q<rcov>, [">= 0"])
+    s.add_dependency(%q<rcov>, [">= 0.9.9"])
     s.add_dependency(%q<nokogiri>, [">= 1.4.4"])
+    s.add_dependency(%q<yard>, [">= 0.6.8"])
   end
 end
 

data/lib/exacttarget.rb

@@ -1,9 +1,5 @@
 # Nokogiri is required for XML parsing:
-begin
-  require 'nokogiri'
-rescue LoadError
-  raise '[ExactTarget] Error: Nokogiri is missing, run "bundle install".'
-end
+require 'nokogiri'
 
 # Standard:
 require 'net/https'
@@ -12,5 +8,151 @@ require 'uri'
 require 'erb'
 
 # Library:
-require 'exacttarget/client'
+require 'exacttarget/job'
+require 'exacttarget/list'
+require 'exacttarget/group'
 require 'exacttarget/email'
+require 'exacttarget/image'
+
+# ExactTarget XML API wrapper.
+#
+# @author Matthew Simpson (matt.simpson@alextom.com)
+# @attr_reader [hash] :config Configuration hash
+#
+class ExactTarget
+  
+  public
+  
+  # Error/warning message header:
+  MSG   = '[ExactTarget]'
+  # For error messages:
+  ERROR = "#{MSG} Error:"
+  # For warning messages:
+  WARN  = "#{MSG} Warning:"
+  # The standard FTP name:
+  FTP_STANDARD_NAME = 'ExactTargetFTP'
+  # The standard FTP URI:
+  FTP_STANDARD_URI  = 'ftp.exacttarget.com'
+  # The standard FTP path (directory):
+  FTP_STANDARD_PATH = '/'
+  # The enhanced FTP name:
+  FTP_ENHANCED_NAME = 'ExactTargetEnhancedFTP'
+  # The enhanced FTP URI:
+  FTP_ENHANCED_URI  = 'ftp1.exacttarget.com'
+  # The enhanced FTP path (directory):
+  FTP_ENHANCED_PATH = '/import'
+  
+  attr_reader :config
+  
+  # Create a new ExactTarget API client.
+  #
+  # @example
+  #  # Simple:
+  #  client = ExactTarget.new :username => 'username', :password => 'password'
+  #
+  #  # Using the enhanced FTP:
+  #  client = ExactTarget.new(
+  #    :username     => 'username',
+  #    :password     => 'password',
+  #    :ftp_username => '123456',
+  #    :ftp_password => '123456',
+  #    :ftp_name     => ExactTarget::FTP_ENHANCED_NAME,
+  #    :ftp_uri      => ExactTarget::FTP_ENHANCED_URI,
+  #    :ftp_path     => ExactTarget::FTP_ENHANCED_PATH
+  #  )
+  #
+  # @param [Hash] config Configuration hash (required)
+  # @option config [String] :username Username (required)
+  # @option config [String] :password Password (required)
+  # @option config [String] :api_uri ExactTarget API URI (needs to be the asp path)
+  # @option config [String] :ftp_username FTP username (default: import)
+  # @option config [String] :ftp_password FTP password (default: import)
+  # @option config [String] :ftp_name FTP name (default: ExactTargetFTP)
+  # @option config [String] :ftp_uri FTP URI (default: ftp.exacttarget.com)
+  # @option config [String] :ftp_path FTP path (defaults to root '/')
+  #
+  def initialize(config)
+    @config = {
+      :username     => nil,
+      :password     => nil,
+      :api_uri      => 'https://api.dc1.exacttarget.com/integrate.asp',
+      :ftp_username => 'import',
+      :ftp_password => 'import',
+      :ftp_name     => FTP_STANDARD_NAME,
+      :ftp_uri      => FTP_STANDARD_URI,
+      :ftp_path     => FTP_STANDARD_PATH
+    }.merge(config)
+    
+    # Sanity check:
+    if @config[:username].nil? || 
+       @config[:password].nil?
+       raise "#{ERROR} username and password required!"
+    end
+    
+    ftp_connect
+    @uri = URI.parse(@config[:api_uri])
+    @api = Net::HTTP.new(@uri.host, @uri.port)
+    @api.use_ssl = true
+  end
+  
+  private
+  
+  def ftp_connect
+    begin
+      @ftp = Net::FTP.new(@config[:ftp_uri])
+      @ftp.login @config[:ftp_username], @config[:ftp_password]
+      @ftp.chdir @config[:ftp_path]
+    rescue => msg
+      puts "#{ERROR} FTP access failed!"
+      raise msg
+    end
+  end
+  
+  def ftp_put(file_path)
+    ftp_connect if @ftp.closed?
+    
+    begin
+      @ftp.noop
+      @ftp.put(file_path.to_s)
+    rescue => msg
+      puts "#{ERROR} FTP put failed!"
+      raise msg
+    end
+  end
+  
+  def ftp_delete(file_name)
+    ftp_connect if @ftp.closed?
+    
+    begin
+      @ftp.noop
+      @ftp.delete(file_name.to_s)
+    rescue => msg
+      puts "#{ERROR} FTP delete failed!"
+      raise msg
+    end
+  end
+  
+  def render(template)
+    path = File.join(File.dirname(__FILE__), "exacttarget/templates/#{template.to_s}.xml.erb")
+    file = File.open(path, 'r').read
+    ERB.new(file, 0, '<>').result(binding)
+  end
+  
+  def send(xml)
+    @system = xml
+    post = 'qf=xml&xml=' + URI.escape(render(:main))
+    
+    begin
+      @api.post(@uri.path, post,
+        {
+          'Content-Type' => 'application/x-www-form-urlencoded',
+          'Content-length' => post.length.to_s
+        }
+      ).body
+    rescue => msg
+      puts "#{ERROR} API request failed."
+      raise msg
+    end
+  end
+    
+end

data/lib/exacttarget/email.rb

@@ -1,135 +1,165 @@
-module ExactTarget
-  class Client
+class ExactTarget
   
-    public
-    
-    def email_find_all(body = false)
-      email_find({ :body => body })
-    end
-    
-    def email_find_by_id(id, options = {})
-      email_find({
-        :id => id,
-        :body => true
-      }.merge(options))
-    end
-    
-    def email_find_by_name(name, options = {})
-      email_find({
-        :name => name,
-      }.merge(options))
-    end
+  public
+  
+  # Find all emails.
+  #
+  # @param [bool] body Retrieve HTML body of each email (can cause seriously lag) [dangerous]
+  #
+  def email_find_all(body = false)
+    email_find({ :body => body })
+  end
+  
+  # Retrieve an email by its ID.
+  #
+  # @param [int,string] id Email ID
+  # @param [hash] options Other options
+  # @see ExactTarget#email_find
+  #
+  def email_find_by_id(id, options = {})
+    email_find({
+      :id => id,
+      :body => true
+    }.merge(options))
+  end
+  
+  # Find all emails who's name includes the given keyword.
+  #
+  # @param [string] name Name of the email (keyword)
+  # @param [hash] options Other options
+  # @see ExactTarget#email_find
+  #
+  def email_find_by_name(name, options = {})
+    email_find({
+      :name => name,
+    }.merge(options))
+  end
+  
+  # Find all emails who's subject includes the given keyword.
+  #
+  # @param [string] subject Subject of the email (keyword)
+  # @param [hash] options Other options
+  # @see ExactTarget#email_find
+  #
+  def email_find_by_subject(subject, options = {})
+    email_find({
+      :subject => subject,
+    }.merge(options))
+  end
+  
+  # Find all emails who's attributes match the selected options.
+  #
+  # @param [hash] options Options hash
+  # @option options [int,string] :id Email ID
+  # @option options [string] :name Name of the email (keyword search)
+  # @option options [string] :subject Subject of the email (keyword search)
+  # @option options [date] :start The date at which to start the search
+  # @option options [date] :end The date at which to end the search
+  # @option options [bool] :body Whether or not to retrieve the HTML body of the email
+  #
+  def email_find(options = {})
+    @action     = 'retrieve'
+    @sub_action = 'all'
+    @type       = ''
+    @value      = ''
     
-    def email_find_by_subject(subject, options = {})
-      email_find({
-        :subject => subject,
-      }.merge(options))
-    end
+    id          = options[:id]      || false
+    name        = options[:name]    || false
+    subject     = options[:subject] || false
+    start_date  = options[:start]   || false
+    end_date    = options[:end]     || false
+    get_body    = options[:body]    || false
+    list        = []
     
-    def email_find(options = {})
-      @action     = 'retrieve'
-      @sub_action = 'all'
-      @type       = ''
-      @value      = ''
-      
-      id          = options[:id]      || false
-      name        = options[:name]    || false
-      subject     = options[:subject] || false
-      start_date  = options[:start]   || false
-      end_date    = options[:end]     || false
-      get_body    = options[:body]    || false
-      list        = []
-      
-      format = Proc.new { |date|
-        begin
-          date if date.instance_of? Date
-          Date.strptime(date, '%m/%d/%Y')
-        rescue
-          raise '[ExactTarget] Error: Invalid date.'
-        end
-      }
-      
-      Nokogiri::Slop(send(render(:email)))
-        .exacttarget
-        .system
-        .email
-        .emaillist.each do |email|
-          (next if email.emailid.content != id.to_s) if id
-          (next if !email.emailname.content.include? name.to_s) if name
-          (next if !email.emailsubject.content.include? subject.to_s) if subject
-          
-          date = format.call(email.emailcreateddate.content)
+    Nokogiri::Slop(send(render(:email)))
+      .exacttarget
+      .system
+      .email
+      .emaillist.each do |email|
+        (next if email.emailid.content != id.to_s) if id
+        (next if !email.emailname.content.include? name.to_s) if name
+        (next if !email.emailsubject.content.include? subject.to_s) if subject
+        
+        date = Date.strptime(email.emailcreateddate.content, '%m/%d/%Y')
+        
+        (next if date < start_date) if start_date && start_date.instance_of?(Date)
+        (next if date > end_date) if end_date && end_date.instance_of?(Date)
+        
+        body = email_get_body(email.emailid.content) if get_body
+        
+        email.instance_eval do
+          new = {
+            :id           => emailid.content,
+            :name         => emailname.content,
+            :subject      => emailsubject.content,
+            :date         => date,
+            :category_id  => categoryid.content
+          }
           
-          (next if date < format.call(start_date)) if start_date
-          (next if date > format.call(end_date)) if end_date
-          
-          body = email_get_body(email.emailid.content) if get_body
-          
-          email.instance_eval do
-            new = {
-              :id           => emailid.content,
-              :name         => emailname.content,
-              :subject      => emailsubject.content,
-              :date         => email.emailcreateddate.content,
-              :category_id  => categoryid.content
-            }
-            
-            new[:body] = body if get_body
-            list << new
-          end
-      end
-      
-      list
+          new[:body] = body if get_body
+          list << new
+        end
     end
     
-    def email_create(name, subject, html, text = false)
-      id = email_add_html(name, subject, html)
-      email_add_text(id, text) if text
-      id
-    end
+    list
+  end
+  
+  # Create an email.
+  #
+  # @param [string] name Name of the new email
+  # @param [string] subject The subject line
+  # @param [string] html The HTML source
+  # @param [string] text The text version
+  #
+  # @see ExactTarget#job_send #email_send (job_send) for sending emails.
+  #
+  def email_create(name, subject, html, text = false)
+    id = email_add_html(name, subject, html)
+    email_add_text(id, text) if text
+    id
+  end
+  
+  private
+  
+  def email_add_html(name, subject, html)
+    @action     = 'add'
+    @sub_action = 'HTMLPaste'
+    @name       = name.to_s
+    @subject    = subject.to_s
+    @body       = html
     
-    private
+    result = Nokogiri::XML(send(render(:email)))
+    id = result.xpath('//emailID').text
     
-    def email_add_html(name, subject, html)
-      @action     = 'add'
-      @sub_action = 'HTMLPaste'
-      @name       = name.to_s
-      @subject    = subject.to_s
-      @body       = html
-      
-      result = Nokogiri::XML(send(render(:email)))
-      id = result.xpath('//emailID').text
-      
-      raise '[ExactTarget] Error: Email HTMLPaste failed.' if id.empty?
-      id
-    end
+    raise "#{ERROR} email HTMLPaste failed." if id.empty?
+    id
+  end
+  
+  def email_add_text(id, text)
+    @action     = 'add'
+    @sub_action = 'text'
+    @id         = id
+    @body       = text
     
-    def email_add_text(id, text)
-      @action     = 'add'
-      @sub_action = 'text'
-      @id         = id
-      @body       = text
-      
-      result = Nokogiri::XML(send(render(:email)))
-      info = result.xpath('//email_info').text
-      
-      raise '[ExactTarget] Error: Email text update failed.' if info.empty?
-      true
-    end
+    result = Nokogiri::XML(send(render(:email)))
+    info = result.xpath('//email_info').text
     
-    def email_get_body(id)
-      @action     = 'retrieve'
-      @sub_action = 'htmlemail'
-      @type       = 'emailid'
-      @value      = id.to_s
-      
-      begin
-        Nokogiri::XML(send(render(:email)))
-          .xpath('//htmlbody').text
-      rescue
-        nil
-      end
-    end
+    raise "#{ERROR} email text update failed." if info.empty?
+    true
+  end
+  
+  def email_get_body(id)
+    @action     = 'retrieve'
+    @sub_action = 'htmlemail'
+    @type       = 'emailid'
+    @value      = id.to_s
     
+    begin
+      Nokogiri::XML(send(render(:email)))
+        .xpath('//htmlbody').text
+    rescue
+      nil
+    end
   end
+  
 end

data/lib/exacttarget/group.rb

@@ -0,0 +1,76 @@
+class ExactTarget
+  
+  public
+  
+  # Retrieve a group by its ID.
+  #
+  # @param [int,string] id Group ID
+  # @param [hash] options Other options
+  # @see ExactTarget#group_find
+  #
+  def group_find_by_id(id, options = {})
+    group_find({
+      :id => id
+    }.merge(options))
+  end
+  
+  # Retrieve a group by its name.
+  #
+  # @param [string] name Group name
+  # @param [hash] options Other options
+  # @see ExactTarget#group_find
+  #
+  def group_find_by_name(name, options = {})
+    group_find({
+      :name => name
+    }.merge(options))
+  end
+  
+  # Retrieve a group by its description.
+  #
+  # @param [string] desc Group description
+  # @param [hash] options Other options
+  # @see ExactTarget#group_find
+  #
+  def group_find_by_desc(desc, options = {})
+    group_find({
+      :desc => desc
+    }.merge(options))
+  end
+  
+  # Find all groups who's attributes match the selected options.
+  #
+  # @param [hash] options Options hash
+  # @option options [int,string] :id Group ID
+  # @option options [string] :name Name of the group (keyword search)
+  # @option options [string] :desc Description of the group (keyword search)
+  #
+  def group_find(options = {})
+    id     = options[:id]   || false
+    name   = options[:name] || false
+    desc   = options[:desc] || false
+    groups = []
+    
+    Nokogiri::Slop(send(render(:group)))
+      .exacttarget
+      .system
+      .list
+      .groups.each do |group|
+        (next if group.groupID.content != id.to_s) if id
+        (next if !group.groupName.content.include? name.to_s) if name
+        (next if !group.description.content.include? desc.to_s) if desc
+        
+        group.instance_eval do
+          groups << {
+            :id   => groupID.content,
+            :name => groupName.content,
+            :desc => description.content
+          }
+        end
+    end
+    groups
+  end
+  
+  alias :group_find_all :group_find
+  
+end

data/lib/exacttarget/image.rb

@@ -1,31 +1,39 @@
-module ExactTarget
-  class Client
+class ExactTarget
   
-    public
+  public
+  
+  # Upload an image (note: uses the FTP and cleans up afterward).
+  #
+  # @param [string] file_path The file path of the image to upload/import
+  #
+  def image_import(file_path)
+    @name  = File.basename(file_path)
+    
+    ftp_put(file_path.to_s)
+    
+    result = Nokogiri::XML(send(render(:image)))
+    desc   = result.xpath('//filemanagement-description').text
+    total  = result.xpath('//filemanagement-totalmoved').text.to_i
+    name   = result.xpath('//filemanagement-info').text
+    error  = desc.include?('not exist') ? 'File not found' : total < 1 ? 'Unsupported file type' : nil
     
-    def image_import(file_path)
-      @name = File.basename(file_path)
-      
-      begin
-        put(file_path.to_s)
-        result = Nokogiri::XML(send(render(:image)))
-        delete(@name)
-      rescue Exception => msg
-        puts msg
-      end
-      
-      desc   = result.xpath('//filemanagement-description').text
-      total  = result.xpath('//filemanagement-totalmoved').text.to_i
-      name   = result.xpath('//filemanagement-info').text
-      error  = desc.include?('not exist') ? 'File not found.' : total < 1 ? 'Unsupported file type.' : nil
-      
-      {
-        :file_path => file_path,
-        :old_name  => @name,
-        :new_name  => name,
-        :error     => error
-      }
+    count  = 0
+    limit  = 15
+    
+    begin
+      sleep 0.5
+      ftp_delete(@name)
+    rescue
+      count += 1
+      retry if count < limit
     end
     
+    {
+      :file_path => file_path.to_s,
+      :old_name  => @name,
+      :new_name  => name,
+      :error     => error
+    }
   end
+  
 end

data/lib/exacttarget/job.rb

@@ -0,0 +1,58 @@
+class ExactTarget
+  
+  public
+  
+  # Send an email to a collection of lists or groups.
+  #
+  # @param [hash] options Options hash
+  # @option options [int,string] :id Email ID
+  # @option options [array] :include The collection of lists or groups to target
+  # @option options [array] :exclude The collection of lists or groups to skip
+  # @option options [string] :from_name Name of sender (only if supported by your account)
+  # @option options [string] :from_email Email address of sender (only if supported by your account)
+  # @option options [string] :additional Additional information to include
+  # @option options [date,datetime] :when The date and/or time which to send the email(s)
+  # @option options [bool] :multipart Whether or not to send in multiple parts (for MIME compatibility)
+  # @option options [bool] :track Whether or not to track hyperlink clicks
+  # @option options [bool] :test If true, suppress email(s) from Performance Reports
+  #
+  def job_send(options)
+    @options = {
+      :id         => nil,
+      :include    => [],
+      :exclude    => [],
+      :from_name  => nil,
+      :from_email => nil,
+      :additional => nil,
+      :when       => nil,
+      :multipart  => false,
+      :track      => true,
+      :test       => false
+    }.merge(options)
+    
+    # Sanity check:
+    if @options[:id].nil? ||
+       @options[:include].empty?
+       raise "#{ERROR} id and include array/string required!"
+    end
+    
+    @date =
+      (@options[:when].strftime('%-m/%-d/%Y') if
+        @options[:when].instance_of?(Date) ||
+        @options[:when].instance_of?(DateTime)) || 'immediate'
+    
+    @time =
+      (@options[:when].strftime('%H:%M') if
+        @options[:when].instance_of?(DateTime)) || ''
+    
+    result = Nokogiri::XML(send(render(:job)))
+    info   = result.xpath('//job_info').text
+    desc   = result.xpath('//job_description').text
+    
+    raise "#{ERROR} job send failed !" if !info.include? 'success'
+    desc
+  end
+  
+  alias :email_send :job_send
+  
+end

data/lib/exacttarget/list.rb

@@ -0,0 +1,109 @@
+class ExactTarget
+  
+  public
+  
+  # Retrieve a list by its ID.
+  #
+  # @param [int,string] id List ID
+  # @param [hash] options Other options
+  # @see ExactTarget#list_find
+  #
+  def list_find_by_id(id, options = {})
+    list_find({
+      :id => id
+    }.merge(options))
+  end
+  
+  # Find all lists who's name includes the given keyword.
+  #
+  # @param [string] name Name of the list (keyword)
+  # @param [hash] options Other options
+  # @see ExactTarget#list_find
+  #
+  def list_find_by_name(name, options = {})
+    list_find({
+      :name => name,
+    }.merge(options))
+  end
+  
+  # Find all lists who's type includes the given keyword.
+  #
+  # @param [string] subject Type of the list (keyword)
+  # @param [hash] options Other options
+  # @see ExactTarget#list_find
+  #
+  def list_find_by_type(type, options = {})
+    list_find({
+      :type => subject,
+    }.merge(options))
+  end
+  
+  # Find all lists who's attributes match the selected options.
+  #
+  # @param [hash] options Options hash
+  # @option options [int,string] :id list ID
+  # @option options [string] :name Name of the list (keyword search)
+  # @option options [string] :type Type of the list (keyword search)
+  # @option options [date] :start The date at which to start the search
+  # @option options [date] :end The date at which to end the search
+  #
+  def list_find(options = {})
+    id         = options[:id]    || false
+    name       = options[:name]  || false
+    type       = options[:type]  || false
+    start_date = options[:start] || false
+    end_date   = options[:end]   || false
+    list       = list_get_all
+    
+    list.select do |item|
+      (next if item[:id] != id.to_s) if id
+      (next if !item[:name].include? name.to_s) if name
+      (next if !item[:type].include? type.to_s) if type
+      (next if item[:modified] < start_date) if start_date && start_date.instance_of?(DateTime)
+      (next if item[:modified] > end_date) if end_date && end_date.instance_of?(DateTime)
+      true
+    end
+  end
+  
+  alias :list_find_all :list_find
+  
+  private
+  
+  def list_get_all
+    @action = 'retrieve'
+    @type   = 'listname'
+    @value  = ''
+    
+    result  = Nokogiri::XML(send(render(:list)))
+    error   = result.xpath('//error_description').text
+    id_list = result.xpath('//listid').map &:text
+    list    = []
+    
+    id_list.each { |id| list << list_get_details(id) } if error.empty?
+    list
+  end
+  
+  def list_get_details(id)
+    @action = 'retrieve'
+    @type   = 'listid'
+    @value  = id.to_s
+    
+    result  = Nokogiri::XML(send(render(:list)))
+    error   = result.xpath('//error_description').text
+    error   = error.empty? ? nil : error
+    
+    {
+      :id           => id.to_s,
+      :name         => result.xpath('//list_name').text,
+      :type         => result.xpath('//list_type').text,
+      :modified     => (DateTime.strptime(result.xpath('//modified').text, '%m/%d/%Y %I:%M:%S %p') if !error),
+      :total        => (result.xpath('//subscriber_count').text.to_i if !error),
+      :subscribed   => (result.xpath('//active_total').text.to_i if !error),
+      :unsubscribed => (result.xpath('//unsub_count').text.to_i if !error),
+      :bounce       => (result.xpath('//bounce_count').text.to_i if !error),
+      :held         => (result.xpath('//held_count').text.to_i if !error),
+      :error        => error
+    }
+  end
+  
+end

data/lib/exacttarget/templates/group.xml.erb

@@ -0,0 +1,7 @@
+<system>
+
+  <system_name>list</system_name>
+  <action>retrievegroups</action>
+  <search_type>groups</search_type>
+  
+</system>

data/lib/exacttarget/templates/image.xml.erb

@@ -3,7 +3,7 @@
   <system_name>filemanagement</system_name>
   <action>filemove</action>
   <source>
-    <location><%= @ftp[:location] %></location>
+    <location><%= @config[:ftp_name] %></location>
     <files>
       <filename><%= @name %></filename>
     </files>

data/lib/exacttarget/templates/job.xml.erb

@@ -0,0 +1,31 @@
+<system>
+
+  <system_name>job</system_name>
+  <action>send</action>
+  <search_type>emailid</search_type>
+  <search_value><%= @options[:id].to_s %></search_value>
+  
+  <from_name><%= @options[:from_name].to_s %></from_name>
+  <from_email><%= @options[:from_email].to_s %></from_email>
+  <additional><%= @options[:additional].to_s %></additional>
+  <multipart_mime><%= @options[:multipart].to_s %></multipart_mime>
+  <track_links><%= @options[:track].to_s %></track_links>
+  
+  <send_date><%= @date %></send_date>
+  <send_time><%= @time %></send_time>
+  
+  <lists>
+    <% @options[:include].each do |id| %>
+      <list><%= id %></list>
+    <% end %>
+  </lists>
+  
+  <suppress>
+    <% @options[:exclude].each do |id| %>
+      <list><%= id %></list>
+    <% end %>
+  </suppress>
+  
+  <test_send><%= @options[:test].to_s %></test_send>
+    
+</system>

data/lib/exacttarget/templates/list.xml.erb

@@ -0,0 +1,11 @@
+<system>
+
+  <system_name>list</system_name>
+  <action><%= @action %></action>
+  
+  <% if @action == 'retrieve' %>
+    <search_type><%= @type %></search_type>
+    <search_value><%= @value %></search_value>
+  <% end %>
+  
+</system>

data/lib/exacttarget/templates/main.xml.erb

@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <exacttarget>
   <authorization>
-    <username><%= @username %></username>
-    <password><%= @password %></password>
+    <username><%= @config[:username] %></username>
+    <password><%= @config[:password] %></password>
   </authorization>
   <%= @system %>
 </exacttarget>

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 3
+  version: 0.1.3
 platform: ruby
 authors: 
 - Matthew Simpson
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-08 00:00:00 -04:00
+date: 2011-05-15 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -25,8 +25,10 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version 
         segments: 
-        - 0
-        version: "0"
+        - 2
+        - 11
+        - 3
+        version: 2.11.3
   type: :development
   prerelease: false
   version_requirements: *id001
@@ -69,7 +71,9 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 0
-        version: "0"
+        - 9
+        - 9
+        version: 0.9.9
   type: :development
   prerelease: false
   version_requirements: *id004
@@ -88,6 +92,21 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: yard
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 6
+        - 8
+        version: 0.6.8
+  type: :development
+  prerelease: false
+  version_requirements: *id006
 description: ExactTarget is a client system for communicating with the ExactTarget email system. The client supports the most up-to-date XML API and is capable of uploading email pastes, images and retrieving lists of subscribers, emails and more.
 email: matt.simpson@alextom.com
 executables: []
@@ -107,11 +126,16 @@ files:
 - VERSION
 - exacttarget.gemspec
 - lib/exacttarget.rb
-- lib/exacttarget/client.rb
 - lib/exacttarget/email.rb
+- lib/exacttarget/group.rb
 - lib/exacttarget/image.rb
+- lib/exacttarget/job.rb
+- lib/exacttarget/list.rb
 - lib/exacttarget/templates/email.xml.erb
+- lib/exacttarget/templates/group.xml.erb
 - lib/exacttarget/templates/image.xml.erb
+- lib/exacttarget/templates/job.xml.erb
+- lib/exacttarget/templates/list.xml.erb
 - lib/exacttarget/templates/main.xml.erb
 has_rdoc: true
 homepage: http://github.com/msimpson/exacttarget
@@ -127,7 +151,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 1328632892447175540
+      hash: 1094960179515826332
       segments: 
       - 0
       version: "0"

data/lib/exacttarget/client.rb

@@ -1,85 +0,0 @@
-module ExactTarget
-  FTP_STANDARD = {
-    :location  => 'ExactTargetFTP',
-    :uri       => 'ftp.exacttarget.com',
-    :path      => '/',
-  }
-  FTP_ENHANCED = {
-    :location  => 'ExactTargetEnhancedFTP',
-    :uri       => 'ftp1.exacttarget.com',
-    :path      => '/import',
-  }
-
-  class Client
-
-    attr_reader :username, :password, :ftp
-    
-    public
-    
-    def initialize(username, password, ftp_username = 'import', ftp_password = 'import', ftp = FTP_STANDARD)
-      @username   = username
-      @password   = password
-      @ftp        = {
-        :username => ftp_username.to_s,
-        :password => ftp_password.to_s,
-        :handle   => Net::FTP.new(ftp[:uri])
-      }.merge ftp
-      
-      begin
-        @ftp[:handle].login @ftp[:username], @ftp[:password]
-        @ftp[:handle].chdir @ftp[:path]
-      rescue Net::FTPPermError => msg
-        puts '[ExactTarget] Error: FTP access failed.'
-        raise msg
-      end
-      
-      @uri = URI.parse('https://api.dc1.exacttarget.com/integrate.asp')
-      @api = Net::HTTP.new(@uri.host, @uri.port)
-      @api.use_ssl = true
-    end
-    
-    private
-    
-    def put(file_path)
-      begin
-        @ftp[:handle].put(file_path.to_s)
-      rescue Exception => msg
-        puts '[ExactTarget] Error: FTP put failed.'
-        raise msg
-      end
-    end
-    
-    def delete(file_name)
-      begin
-        @ftp[:handle].delete(file_name.to_s)
-      rescue Exception => msg
-        puts '[ExactTarget] Error: FTP delete failed.'
-        raise msg
-      end
-    end
-        
-    def render(template)
-      path = File.join(File.dirname(__FILE__), "templates/#{template.to_s}.xml.erb")
-      file = File.open(path, 'r').read
-      ERB.new(file, 0, '<>').result(binding)
-    end
-    
-    def send(xml)
-      @system = xml
-      post = 'qf=xml&xml=' + URI.escape(render(:main))
-      
-      begin
-        @api.post(@uri.path, post,
-          {
-            'Content-Type' => 'application/x-www-form-urlencoded',
-            'Content-length' => post.length.to_s
-          }
-        ).body
-      rescue SocketError => msg
-        puts '[ExactTarget] Error: API request failed.'
-        raise msg
-      end
-    end
-    
-  end
-end