etapi 0.1.1

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.DS_Store

data/Gemfile

@@ -0,0 +1,3 @@
+source(:rubygems)
+
+gemspec

data/README.md

@@ -0,0 +1,34 @@
+ExactTarget API Wrapper
+=======================
+
+ETAPI is an ExactTarget API wrapper for XML calls.
+
+Documentation
+------------
+[Wiki](https://github.com/Phiction/etapi/wiki)
+
+TODO
+====
+
+Subscriber Management
+---
+`subscriber_add` : add s4 `:account_id`, add `:status`  
+`subscriber_edit` : add s4 `:account_id`, add `:status`  
+`subscriber_retrieve` : add s4 `:account_id`, add `:status`  
+`subscriber_retrieve_from_list`  
+`subscriber_retrieve_from_list` : add s4 `:account_id`, add `:status`  
+`subscriber_retrieve_lists`  
+`subscriber_retrieve_lists` : add s4 `:account_id`, add `:status`  
+`subscriber_unsubscribe_master` : multiple email addresses
+
+List Management
+---
+`list_retrieve_subscribers` : add s4 `:account_id`, add `:status`  
+
+Email Management
+---
+`email_retrieve_body` : have access to sub accounts?  
+
+XML
+===
+Any other XML calls available will be added by request

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/etapi.gemspec

@@ -0,0 +1,22 @@
+lib = File.expand_path("../lib", __FILE__)
+$:.unshift lib unless $:.include? lib
+
+require "etapi/version"
+
+Gem::Specification.new do |s|
+  s.name        = "etapi"
+  s.version     = ETAPI::Version
+  s.authors     = ["Chris McGrath"]
+  s.email       = ["mcgrath.chris@gmail.com"]
+  s.homepage    = %q{http://github.com/phiction/etapi}
+  s.summary     = %q{Ruby Wrapper for Exact Target's APIs}
+  s.description = %q{This is an attempt to make integrating easier with Exact Target's XML APIs.}
+
+  s.rubyforge_project = "etapi"
+  
+  s.add_dependency("builder",   ">= 2.1.2")
+  s.add_dependency("nokogiri",  ">= 1.4.1")
+  
+  s.files         = `git ls-files`.split("\n")
+  s.require_path  = "lib"
+end

data/lib/etapi/call_builder.rb

@@ -0,0 +1,70 @@
+module ETAPI
+  
+  class Session
+    
+    def build_call(type, method, *args)
+      
+      options         = args.extract_options!
+      ignore_parse  = options[:ignore_parse] || false
+      
+      data = ""
+      xml = Builder::XmlMarkup.new(:target => data, :indent => 2)
+      xml.instruct!
+      xml.exacttarget do
+        xml.authorization do
+          xml.username @username
+          xml.password @password
+        end
+        xml.system do
+          xml.system_name type
+          xml.action method
+          for parameter in @parameters
+            if parameter[0] == "values"
+              xml.values do
+                parameter[1].each do |key, value|
+                  eval("xml.#{key.gsub(/\s/, '__')} '#{value}'")
+                end
+              end
+            else
+              if parameter[1].is_a?(Hash)
+                xml.tag!(parameter[0]) do
+                  parameter[1].each do |key, value|
+                    eval("xml.#{key.gsub(/\s/, '__')} '#{value}'")
+                  end
+                end
+              else
+                eval("xml.#{parameter[0]} '#{parameter[1]}'")
+              end
+            end
+          end
+        end
+      end
+      
+      data_encoded = "qf=xml&xml=" + url_encode(data)
+      response = @api_url.post(@api_uri.path, data_encoded, @headers.merge('Content-length' => data_encoded.length.to_s))
+      check_response(response)
+      ignore_parse ? response.read_body : Nokogiri::XML::Document.parse(response.read_body)
+      
+    end
+    
+    private
+    
+    def print_xml(obj)
+      require "rexml/document"
+      doc = REXML::Document.new(obj.http.raw_body)
+      out = ""
+      doc.write(out, 1)
+      out
+    end
+    
+    def print_full_xml(obj)
+      require "rexml/document"
+      doc = REXML::Document.new(obj)
+      out = ""
+      doc.write(out, 1)
+      out
+    end
+    
+  end
+  
+end

data/lib/etapi/calls/email.rb

@@ -0,0 +1,33 @@
+module ETAPI
+  
+  class Session
+    
+    def email_retrieve_body(*args)
+      
+      # options
+      options         = args.extract_options!
+      @email_id       = options[:email_id]
+      
+      # check for required options
+      required_options = ["email_id"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      type        = "email"
+      method      = "retrieve"
+      @parameters = {
+        "search_type"   => "emailid",
+        "sub_action"    => "htmlemail",
+        "search_value"  => @email_id,
+        "search_value2" => "",
+        "search_value3" => "",
+      }
+      
+      response = build_call(type, method)
+      response.xpath("//htmlbody").text rescue false
+      
+    end
+    
+  end
+  
+end

data/lib/etapi/calls/list.rb

@@ -0,0 +1,28 @@
+module ETAPI
+  
+  class Session
+    
+    def list_retrieve_subscribers(*args)
+      
+      # options
+      options         = args.extract_options!
+      @list_id        = options[:list_id]
+      
+      # check for required options
+      required_options = ["list_id"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "listid",
+        "search_value"  => @list_id
+      }
+      
+      response = build_call("list", "retrieve_sub", {:parse_response => false})
+      Hash.from_xml(response)['exacttarget']['system']['list']['subscribers'].first[1] rescue false
+      
+    end
+    
+  end
+  
+end

data/lib/etapi/calls/subscriber.rb

@@ -0,0 +1,178 @@
+module ETAPI
+  
+  class Session
+    
+    def subscriber_add(*args)
+      
+      # options
+      options           = args.extract_options!
+      @list_id          = options[:list_id] ||= nil
+      @email            = options[:email]
+      @values           = options[:values] ||= {}
+      @account_id       = options[:account_id]
+      
+      # check for required options
+      required_options = ["email", "list_id"]
+      return false unless check_required(required_options)
+      
+      # update options
+      @values.merge!({"Email Address" => @email, "status" => "active"})
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "listid",
+        "search_value"  => @list_id,
+        "search_value2" => "",
+        "values"        => @values
+      }
+      
+      response = build_call("subscriber", "add")
+      response.xpath("//subscriber_description").text.to_i rescue false
+      
+    end
+    
+    def subscriber_edit(*args)
+      
+      # options
+      options         = args.extract_options!
+      @subscriber_id  = options[:subscriber_id]
+      @values         = options[:values] ||= {}
+      @account_id     = options[:account_id] ||= ""
+      
+      # check for required options
+      required_options = ["subscriber_id"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "subid",
+        "search_value"  => @subscriber_id,
+        "search_value2" => "",
+        "values"        => @values
+      }
+      
+      response = build_call("subscriber", "edit")
+      response.xpath("//subscriber_description").text == @subscriber_id.to_s rescue false
+      
+    end
+    
+    def subscriber_edit_from_list(*args)
+      
+      # options
+      options         = args.extract_options!
+      @list_id        = options[:list_id]
+      @email          = options[:email]
+      @values         = options[:values] ||= {}
+      @account_id     = options[:account_id] ||= ""
+      
+      # check for required options
+      required_options = ["list_id", "email"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "listid",
+        "search_value"  => @list_id,
+        "search_value2" => @email,
+        "values"        => @values
+      }
+      
+      response = build_call("subscriber", "edit")
+      response.xpath("//subscriber_description").text.blank? && response.xpath("//subscriber_info").text.blank? ? false : true rescue false
+      
+    end
+    
+    def subscriber_delete(*args)
+      
+      # options
+      options         = args.extract_options!
+      @subscriber_id  = options[:subscriber_id]
+      
+      # check for required options
+      required_options = ["subscriber_id"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "subid",
+        "search_value"  => @subscriber_id,
+        "search_value2" => ""
+      }
+      
+      response = build_call("subscriber", "delete")
+      response.xpath("//subscriber_info").text.blank? ? false : true rescue false
+      
+    end
+    
+    def subscriber_remove_from_list(*args)
+      
+      # options
+      options         = args.extract_options!
+      @list_id        = options[:list_id]
+      @email          = options[:email]
+      
+      # check for required options
+      required_options = ["list_id", "email"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "listid",
+        "search_value"  => @list_id,
+        "search_value2" => @email
+      }
+      
+      response = build_call("subscriber", "delete")
+      response.xpath("//subscriber_info").text.blank? ? false : true rescue false
+      
+    end
+    
+    def subscriber_unsubscribe_master(*args)
+      
+      # options
+      options         = args.extract_options!
+      @email          = options[:email]
+      
+      # check for required options
+      required_options = ["email"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "emailaddress",
+        "search_value"  => {
+          "emailaddress" => @email
+        }
+      }
+      
+      response = build_call("subscriber", "masterunsub")
+      response.xpath("//emailaddress").text == @email ? true : false rescue false
+      
+    end
+    
+    def subscriber_retrieve(*args)
+      
+      # options
+      options         = args.extract_options!
+      @subscriber_id  = options[:subscriber_id]
+      @account_id     = options[:account_id] ||= ""
+      
+      # check for required options
+      required_options = ["subscriber_id"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      @parameters = {
+        "search_type"   => "subid",
+        "search_value"  => @subscriber_id,
+        "search_value2" => ""
+      }
+      
+      response = build_call("subscriber", "retrieve", {:ignore_parse => true})
+      Hash.from_xml(response)['exacttarget']['system']['subscriber'].first rescue false
+      
+    end
+    
+  end
+  
+end

data/lib/etapi/calls/tracking.rb

@@ -0,0 +1,32 @@
+module ETAPI
+  
+  class Session
+    
+    def tracking_retrieve(*args)
+      
+      # options
+      options         = args.extract_options!
+      @job_id         = options[:job_id]
+      
+      # check for required options
+      required_options = ["job_id"]
+      return false unless check_required(required_options)
+      
+      # merge parameters and values
+      type        = "tracking"
+      method      = "retrieve"
+      @parameters = {
+        "search_type"   => "jobID",
+        "sub_action"    => "summary",
+        "search_value"  => @job_id,
+        "search_value2" => ""
+      }
+      
+      response = build_call(type, method, {:parse_response => false})
+      Hash.from_xml(response)['exacttarget']['system']['tracking']['emailSummary'] rescue false
+      
+    end
+    
+  end
+  
+end

data/lib/etapi/configuration.rb

@@ -0,0 +1,49 @@
+require("erb")
+require("uri")
+require("logger")
+require("builder")
+require("nokogiri")
+require("net/https")
+require("etapi/error")
+require("etapi/exact_target")
+require("etapi/call_builder")
+
+include(ERB::Util)
+
+module ETAPI
+  module Configuration
+    
+    attr_accessor(
+      :username,
+      :password,
+      :use_s4,
+      :raise_errors,
+      :log
+    )
+    
+    attr_writer(:log)
+    def log?
+     @log != false
+    end
+    
+    def log(message)
+     logger.send(log_level, "\n#{message}\n") if log?
+    end
+    
+    attr_writer(:logger)
+    def logger
+      @logger ||= ::Logger.new(STDOUT)
+    end
+    
+    attr_writer(:log_level)
+    def log_level
+      @log_level ||= :debug
+    end
+    
+    attr_writer(:raise_errors)
+    def raise_errors?
+      @raise_errors != false
+    end
+    
+  end
+end

data/lib/etapi/error.rb

@@ -0,0 +1,46 @@
+module ETAPI
+  
+  class Session
+    
+    def check_response(response)
+      
+      raise Error.new(-1, 'Network error') if response.class != Net::HTTPOK
+      
+      response = Nokogiri::XML::Document.parse(response.body)
+      
+      error_code  = response.xpath("//error")
+      error_msg   = response.xpath("//error_description")
+      
+      if !error_code.blank? && !error_msg.blank?
+        if ETAPI.raise_errors?
+          raise(RuntimeError, "\n\n    Code:    #{error_code.text.to_i}\n    Message: #{error_msg.text}\n\n")
+        else
+          ETAPI.log("    Code:    #{error_code.text.to_i}\n    Message: #{error_msg.text}") if ETAPI.log?
+          return false
+        end
+      end
+      
+    end
+    
+    def check_required(required_options)
+      missing_options = []
+      
+      for option in required_options
+        missing_options << ":#{option}" if eval("@#{option}.blank?")
+      end
+      
+      if !missing_options.blank?
+        if ETAPI.log?
+          ETAPI.log("    Code:    ETAPI\n    Message: missing #{missing_options.join(', ')}")
+        elsif ETAPI.raise_errors?
+          raise(ArgumentError, "\n\n    Code:    ETAPI\n    Message: missing #{missing_options.join(', ')}\n\n")
+        end
+        return false
+      end
+      
+      return true
+    end
+    
+  end
+  
+end

data/lib/etapi/exact_target.rb

@@ -0,0 +1,52 @@
+require("etapi/calls/list")
+require("etapi/calls/email")
+require("etapi/calls/tracking")
+require("etapi/calls/subscriber")
+
+module ETAPI
+  
+  class Session
+    
+    # set default options
+    DEFAULTS = {
+      :api_method           => :xml,
+      :use_s4               => false,
+      :api_uri_xml          => "https://api.dc1.exacttarget.com/integrate.aspx",
+      :api_uri_xml_s4       => "https://api.s4.exacttarget.com/integrate.aspx",
+      :use_ssl              => true,
+    }
+    
+    # allowed options
+    ALLOWED_USE_S4_OPTIONS      = [true, false]
+    
+    # initialize a new exact target instance
+    def initialize(*args)
+      
+      # merge options with configuration
+      options     = args.extract_options!
+      @username   = options[:username]    ||= ETAPI.username
+      @password   = options[:password]    ||= ETAPI.password
+      @use_s4     = options[:use_s4]      ||= ETAPI.use_s4     ||= DEFAULTS[:use_s4]
+      @headers    = {"Content-Type" => "application/x-www-form-urlencoded", "Connection" => "close"}
+      
+      # check for required options
+      raise ArgumentError, "* missing :username *" if @username.blank?
+      raise ArgumentError, "* missing :password *" if @password.blank?
+      raise ArgumentError, "* invalid :use_s4 | options => [true, false] *" unless ALLOWED_USE_S4_OPTIONS.include?(@use_s4)
+      
+      @api_uri = @use_s4 ? DEFAULTS[:api_uri_xml_s4] : DEFAULTS[:api_uri_xml]
+      
+      @api_wsdl = @api_uri if @use_s4
+      
+      # parse uri
+      @api_uri   = URI.parse(@api_uri)
+      @api_url   = Net::HTTP.new(@api_uri.host, @api_uri.port)
+      
+      # check for SSL (disabled)
+      @api_url.use_ssl = options[:use_ssl] ||= DEFAULTS[:use_ssl]
+      
+    end
+    
+  end
+  
+end

data/lib/etapi/version.rb

@@ -0,0 +1,3 @@
+module ETAPI
+  Version = "0.1.1"
+end

data/lib/etapi.rb

@@ -0,0 +1,10 @@
+require("etapi/configuration")
+
+module ETAPI
+  extend Configuration
+  
+  def self.configure
+    yield self if block_given?
+  end
+  
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: etapi
+version: !ruby/object:Gem::Version 
+  hash: 25
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 1
+  version: 0.1.1
+platform: ruby
+authors: 
+- Chris McGrath
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-09-03 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: builder
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 15
+        segments: 
+        - 2
+        - 1
+        - 2
+        version: 2.1.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 1
+        - 4
+        - 1
+        version: 1.4.1
+  type: :runtime
+  version_requirements: *id002
+description: This is an attempt to make integrating easier with Exact Target's XML APIs.
+email: 
+- mcgrath.chris@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- etapi.gemspec
+- lib/etapi.rb
+- lib/etapi/call_builder.rb
+- lib/etapi/calls/email.rb
+- lib/etapi/calls/list.rb
+- lib/etapi/calls/subscriber.rb
+- lib/etapi/calls/tracking.rb
+- lib/etapi/configuration.rb
+- lib/etapi/error.rb
+- lib/etapi/exact_target.rb
+- lib/etapi/version.rb
+homepage: http://github.com/phiction/etapi
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: etapi
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Ruby Wrapper for Exact Target's APIs
+test_files: []
+