exact-target 0.0.4

data/Manifest

@@ -0,0 +1,22 @@
+CHANGELOG
+LICENSE
+README.rdoc
+Rakefile
+lib/exact_target.rb
+lib/exact_target/builder_ext.rb
+lib/exact_target/configuration.rb
+lib/exact_target/error.rb
+lib/exact_target/net_https_hack.rb
+lib/exact_target/request_builder.rb
+lib/exact_target/response_class.erb
+lib/exact_target/response_classes.rb
+lib/exact_target/response_handler.rb
+lib/exact_target/string_ext.rb
+spec/exact_target/net_https_hack_spec.rb
+spec/exact_target/response_handler_spec.rb
+spec/exact_target/string_ext_spec.rb
+spec/exact_target_data.yml
+spec/exact_target_spec.rb
+spec/spec.opts
+spec/subscriber_list_spec.rb
+Manifest

data/README.rdoc

@@ -0,0 +1,170 @@
+= ExactTarget - A Ruby interface to the ExactTarget API.
+
+== Introduction
+
+ExactTarget is an email marketing solution provider with an
+http-based api for performing various tasks such as managing
+mailing lists, managing subscribers, and queueing up email
+jobs.  This gem is a pure ruby library for accessing that api.
+
+== Resources
+
+=== Installation
+
+  gem install exact-target
+
+=== Git Repository
+
+http://github.com/ePublishing/exact_target
+
+== Prerequisites
+
+The ExactTarget gem depends on both Nokogiri and Builder. Both
+should be installed automatically when them gem is installed
+(if not already installed).
+
+== Notes
+
+Currently this is a partial implementation.  None of the
+tracking functionality is yet implemented.
+
+== Usage
+
+=== Setup/Configuration
+
+  require 'exact_target'
+
+  ExactTarget.configure do |config|
+    config.username = 'my_username'
+    config.password = 'my_password'
+  end
+
+=== Account Information
+
+  # Retrieve subscriber attributes
+  ExactTarget.accountinfo_retrieve_attrbs
+
+=== List Management
+
+  # Retrieve all list ids
+  ExactTarget.list_retrieve
+
+  # Retrieve list id for given name
+  ExactTarget.list_retrieve('Some List')
+
+  # Retrieve list information by list id
+  ExactTarget.list_retrieve(15123512)
+
+  # Create new list
+  ExactTarget.list_add("My Test List", :private)
+
+  # Rename a list
+  ExactTarget.list_edit(15123512, "My RENAMED Test List")
+
+  # Import new or updated subscribers en mass from a comma-delimited
+  # or tab-delimited file into an existing subscriber list.
+  ExactTarget.list_import(15123512, 'sometestfile.txt', ['Email Address', 'Field 2', ...])
+  ExactTarget.list_import([id_1, id2, ...], 'sometestfile.txt', ['Email Address', 'Field 2', ...])
+
+  # Request an update on the status of an import.
+  ExactTarget.list_importstatus(some_import_id)
+
+  # Retrieve the profile and preference attributes for all subscribers
+  # (or all subscribers with a certain status) on a specified list.
+  ExactTarget.list_retrieve_sub(42, 'Active')
+
+  # Delete a list and all subscribers who belong to the list.
+  ExactTarget.list_delete(15123512)
+
+  # Retrieve all groups in your account.
+  ExactTarget.list_retrievegroups
+
+  # Refresh the membership of an attribute-based (rule-based) group
+  # to reflect any changes to your subscribers' attribute values.
+  ExactTarget.list_refresh_group(3514)
+
+  # Request an update on the status of a group refresh.
+  ExactTarget.batch_inquire(8912)
+
+=== Subscriber Management
+
+  # Add a subscriber to a list.
+  subscriber = ExactTarget::Subscriber.new.tap do |s|
+    s.email_address = 'test.person@company.com'
+    s.full_name     = 'George Wills'
+  end
+  ExactTarget.subscriber_add(1234, subscriber,
+                             :status => :active,
+                             :update => true,
+                             :ChannelMemberID => 5678)
+
+  # Update the attributes (including email address) and/or status of
+  # an existing subscriber. Can be used to reactivate a subscriber
+  # who was placed on the master unsubscribe list.
+  subscriber = ExactTarget::Subscriber.new.tap do |s|
+    s.email_address = 'new.email@company.com'
+    s.full_name     = 'Frank Jones'
+  end
+  ExactTarget.subscriber_edit(63718, 'previous@email.com', subscriber,
+                              :status => :unsub,
+                              :reason => 'Some reason ...',
+                              :ChannelMemberID => 5678)
+
+  # Retrieve all profile and preference attribute data entered for a
+  # subscriber on a specific list, or retrieve all attribute data for
+  # a subscriber and all lists to which the subscriber belongs.
+  ExactTarget.subscriber_retrieve(123456, 'someone@example.com')
+  ExactTarget.subscriber_retrieve(123456789)
+
+  # Delete a subscriber from your database, or remove a subscriber
+  # from a specified list.
+  ExactTarget.subscriber_delete(112233445566, 'bob@hotmail.com')
+  ExactTarget.subscriber_delete(112233445566)
+
+  # Place a subscriber's (or multiple subscribers') email address on
+  # your Master Unsubscribe list so that the email address is never
+  # added to any of your subscriber lists.
+  ExactTarget.subscriber_masterunsub 'someone@email.com', 'someone.else@email.com', ...
+
+=== Mailing Management
+
+  # Retrieve all email IDs or filter by email name and/or date range.
+  ExactTarget.email_retrieve
+  ExactTarget.email_retrieve('Welcome to Fortune One!')
+  ExactTarget.email_retrieve(:start_date => Date.parse('2008-09-15'),
+                             :end_date => Date.parse('2008-10-15'))
+  ExactTarget.email_retrieve('Welcome to Fortune One!',
+                             :start_date => Date.parse('2008-09-15'),
+                             :end_date => Date.parse('2008-10-15'))
+
+  # Create an email from HTML that you send to the ExactTarget application via an API call.
+  ExactTarget.email_add('Your email name', 'Your subject line', :body => 'Your HTML email body')
+  ExactTarget.email_add('Your email name', 'Your subject line', :file => 'Filename')
+
+  # Create the text version of an email, which will be displayed
+  # to any subscriber whose email client does not support HTML email.
+  ExactTarget.email_add_text(email_id, :body => 'Your text email body')
+  ExactTarget.email_add_text(email_id, :file => 'Filename')
+
+  # Retrieve the body of the HTML version of any email in your account.
+  ExactTarget.email_retrieve_body(email_id)
+
+=== Job Initiation
+
+  # Kick off a mailing (test or live)
+  ExactTarget.job_send(email_id,
+                       [list_id_1, list_id_2, ...],
+                       :suppress_ids => [list_id_3, ...],
+                       :from_name => 'John Doe',
+                       :from_email => 'jd@nowhere.com',
+                       :additional => 'additional information for job',
+                       :multipart_mime => true,
+                       :track_links => false,
+                       :send_date => '5/3/2011',
+                       :send_time => '17:35',
+                       :test_send => true)
+
+---
+Author::   David McCullars <mailto:dmccullars@ePublishing.com>
+Copyright:: (C) 2011 ePublishing
+Licence::  GPL[http://www.gnu.org/copyleft/gpl.html]

data/Rakefile

@@ -0,0 +1,40 @@
+require 'rake'
+require 'echoe'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+task :default => :gem
+
+Echoe.new("exact-target") do |s|
+  s.author = "David McCullars"
+  s.project = "exact-target"
+  s.email = "dmccullars@ePublishing.com"
+  s.url = "http://github.com/ePublishing/exact_target"
+  s.docs_host = "http://rdoc.info/github/ePublishing/exact_target/master/frames"
+  s.rdoc_pattern = /README|TODO|LICENSE|CHANGELOG|BENCH|COMPAT|exceptions|behaviors|exact-target.rb/
+  s.clean_pattern += ["ext/lib", "ext/include", "ext/share", "ext/libexact-target-?.??", "ext/bin", "ext/conftest.dSYM"]
+  s.summary = <<DONE
+This is a pure-ruby implementation of the ExactTarget api.
+For more information consule http://www.exacttarget.com/.
+DONE
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_opts = ['--options', %q("spec/spec.opts")]
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end
+
+desc 'generate API documentation to doc/rdocs/index.html'
+Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = 'doc/rdocs'
+  rd.main = 'README.rdoc'
+  rd.rdoc_files.include 'README.rdoc', 'CHANGELOG', 'lib/**/*.rb'
+  rd.rdoc_files.exclude '**/string_ext.rb', '**/net_https_hack.rb'
+  rd.options << '--inline-source'
+  rd.options << '--line-numbers'
+  rd.options << '--all'
+  rd.options << '--fileboxes'
+end

data/exact-target.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{exact-target}
+  s.version = "0.0.4"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["David McCullars"]
+  s.date = %q{2011-04-11}
+  s.description = %q{This is a pure-ruby implementation of the ExactTarget api.
+For more information consule http://www.exacttarget.com/.
+}
+  s.email = %q{dmccullars@ePublishing.com}
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "README.rdoc"]
+  s.files = ["CHANGELOG", "LICENSE", "README.rdoc", "Rakefile", "lib/exact_target.rb", "lib/exact_target/builder_ext.rb", "lib/exact_target/configuration.rb", "lib/exact_target/error.rb", "lib/exact_target/net_https_hack.rb", "lib/exact_target/request_builder.rb", "lib/exact_target/response_class.erb", "lib/exact_target/response_classes.rb", "lib/exact_target/response_handler.rb", "lib/exact_target/string_ext.rb", "spec/exact_target/net_https_hack_spec.rb", "spec/exact_target/response_handler_spec.rb", "spec/exact_target/string_ext_spec.rb", "spec/exact_target_data.yml", "spec/exact_target_spec.rb", "spec/spec.opts", "spec/subscriber_list_spec.rb", "Manifest", "exact-target.gemspec"]
+  s.homepage = %q{http://github.com/ePublishing/exact_target}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Exact-target", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{exact-target}
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{This is a pure-ruby implementation of the ExactTarget api. For more information consule http://www.exacttarget.com/.}
+
+  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/lib/exact_target.rb

@@ -0,0 +1,109 @@
+require 'date'
+require 'net/http'
+require 'net/https'
+require 'nokogiri'
+require 'uri'
+
+require 'exact_target/net_https_hack'
+require 'exact_target/builder_ext'
+require 'exact_target/string_ext'
+
+require 'exact_target/configuration'
+require 'exact_target/error'
+require 'exact_target/request_builder'
+require 'exact_target/response_classes'
+require 'exact_target/response_handler'
+
+# The ExactTarget library is a ruby implementation of the ExactTarget
+# email marketing api.  It allows for list/subscriber management,
+# email creation, and job initiation.
+module ExactTarget
+
+  VERSION = File.read(File.expand_path '../../CHANGELOG', __FILE__)[/v([\d\.]+)\./, 1]
+  LOG_PREFIX = "** [ExactTarget] "
+
+  extend ExactTarget::ResponseClasses
+
+  class << self
+    # The builder object is responsible for building the xml for any given request
+    attr_accessor :builder
+
+    # The handler object is responsible for handling the xml response and returning
+    # response data
+    attr_accessor :handler
+
+    # A ExactTarget configuration object. Must act like a hash and return sensible
+    # values for all ExactTarget configuration options. See ExactTarget::Configuration.
+    attr_accessor :configuration
+
+    def configure(username=nil, password=nil)
+      self.configuration ||= Configuration.new
+      configuration.username = username if username
+      configuration.password = password if password
+      yield(configuration) if block_given?
+      self.builder = RequestBuilder.new(configuration)
+      self.handler = ResponseHandler.new(configuration)
+      nil
+    end
+
+    def verify_configure
+      raise "ExactTarget must be configured before using" if configuration.nil? or !configuration.valid?
+    end
+
+    def log(level, message)
+      verify_configure
+      configuration.logger.send(level, message) unless configuration.logger.nil?
+    end
+
+    def call(method, *args, &block)
+      verify_configure
+
+      request = builder.send(method, *args, &block)
+      log :debug, "#{LOG_PREFIX}REQUEST: #{request}"
+
+      response = send_to_exact_target(request)
+      log :debug, "#{LOG_PREFIX}RESPONSE: #{response}"
+
+      response = parse_response_xml(response)
+
+      handler.send(method, response)
+    end
+
+    def send_to_exact_target(request)
+      verify_configure
+      uri = URI.parse "#{configuration.base_url}?qf=xml&xml=#{URI.escape request}"
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = configuration.secure?
+      http.open_timeout = configuration.http_open_timeout
+      http.read_timeout = configuration.http_read_timeout
+      resp = http.get(uri.request_uri)
+      if resp.is_a?(Net::HTTPSuccess)
+        resp.body
+      else
+        resp.error!
+      end
+    end
+
+    # Define ExactTarget methods
+    (RequestBuilder.instance_methods(false) & ResponseHandler.instance_methods(false)).each do |m|
+      define_method(m) do |*args, &block|
+        call(m, *args, &block)
+      end
+    end
+
+    private
+
+    def parse_response_xml(xml)
+      verify_configure
+      resp = Nokogiri.parse(xml)
+      error = resp.xpath('//error[1]').first
+      error_description = resp.xpath('//error_description[1]').first
+      if error and error_description
+        raise Error.new(error.text.to_i, error_description.text)
+      else
+        resp
+      end
+    end
+  end
+
+end

data/lib/exact_target/builder_ext.rb

@@ -0,0 +1,11 @@
+require 'builder'
+
+Builder::XmlBase.class_eval do
+
+  def tags_from_options!(options, *names)
+    names.flatten.each do |name|
+      tag! name.to_s, options[name.to_sym].to_s
+    end
+  end
+
+end

data/lib/exact_target/configuration.rb

@@ -0,0 +1,42 @@
+module ExactTarget
+  # Used to set up and modify settings for ExactTarget
+  class Configuration
+
+    OPTIONS = [:base_url, :username, :password,
+               :http_open_timeout, :http_read_timeout].freeze
+
+    # The (optional) base URL for accessing ExactTarget (can be http or https).
+    # Defaults to 'https://api.dc1.exacttarget.com/integrate.aspx'
+    attr_accessor :base_url
+
+    # The (required) ExactTarget username for making requests
+    attr_accessor :username
+
+    # The (required) ExactTarget password for making requests
+    attr_accessor :password
+
+    # The (optional) logger for outputting request/resposne xml
+    attr_accessor :logger
+
+    # The (optional) HTTP open timeout in seconds (defaults to 2).
+    attr_accessor :http_open_timeout
+
+    # The (optional) HTTP read timeout in seconds (defaults to 5).
+    attr_accessor :http_read_timeout
+
+    def initialize
+      @base_url                 = 'https://api.dc1.exacttarget.com/integrate.aspx'
+      @http_open_timeout        = 2
+      @http_read_timeout        = 5
+    end
+
+    def valid?
+      [:base_url, :username, :password].none? { |f| send(f).nil? }
+    end
+
+    def secure?
+      !!(base_url =~ /^https:/i)
+    end
+
+  end
+end

data/lib/exact_target/error.rb

@@ -0,0 +1,16 @@
+module ExactTarget
+  class Error < Exception
+
+    attr_reader :id, :description
+
+    def initialize(id, description)
+      @id = id
+      @description = description
+    end
+
+    def to_s
+      "ExactTarget error ##{id}: #{description}"
+    end
+
+  end
+end