marketo-api-ruby 0.8

data/lib/marketo_api/client.rb

@@ -0,0 +1,169 @@
+require 'savon'
+require 'openssl'
+
+##
+# The client to the Marketo SOAP API.
+class MarketoAPI::Client
+  DEFAULT_CONFIG = {
+    api_subdomain:     '123-ABC-456',
+    api_version:       '2_3',
+    user_id:           nil,
+    encryption_key:    nil,
+    read_timeout:      90,
+    open_timeout:      90,
+    headers:           { 'Connection' => 'Keep-Alive' },
+    env_namespace:     'SOAP-ENV',
+    namespaces:        { 'xmlns:ns1' => 'http://www.marketo.com/mktows/' },
+    pretty_print_xml:  true,
+    ssl_verify_mode:   :none,
+  }.freeze
+  DEFAULT_CONFIG.values.each(&:freeze)
+  private_constant :DEFAULT_CONFIG
+
+  # Sets the logger.
+  attr_writer :logger
+
+  # The targeted Marketo SOAP API version.
+  attr_reader :api_version
+  # The subdomain for interacting with Marketo.
+  attr_reader :subdomain
+  # The WSDL used for interacting with Marketo.
+  attr_reader :wsdl
+  # The computed endpoint for Marketo.
+  attr_reader :endpoint
+  # If the most recent call resulted in an exception, it will be captured
+  # here.
+  attr_reader :error
+
+  # Creates a client to talk to the Marketo SOAP API.
+  #
+  # === Required Configuration Parameters
+  #
+  # The required configuration parameters can be found in your Marketo
+  # dashboard, under Admin / Integration / SOAP API.
+  #
+  # +api_subdomain+::  The endpoint subdomain.
+  # +api_version+::    The endpoint version.
+  # +user_id+::        The user iD for SOAP integration.
+  # +encryption_key+:: The encryption key for SOAP integration.
+  #
+  # Version 1.0 will make these values defaultable through environment
+  # variables.
+  #
+  # === Savon Configuration Parameters
+  #
+  # These affect how Savon interacts with the HTTP server.
+  #
+  # +read_timeout+::     The timeout for reading from the server. Defaults
+  #                      to 90.
+  # +open_timeout+::     The timeout for opening the connection. Defaults to
+  #                      90.
+  # +pretty_print_xml+:: How the SOAP XML should be written. Defaults to
+  #                      +true+.
+  # +ssl_verify_mode+::  How to verify SSL keys. This version defaults to
+  #                      +none+. Version 1.0 will default to normal
+  #                      verification.
+  # +headers+::          Headers to use. Defaults to Connection: Keep-Alive.
+  #                      Version 1.0 will enforce at least this value.
+  #
+  # Version 1.0 will require that these options be provided under a +savon+
+  # key.
+  def initialize(config = {})
+    config = DEFAULT_CONFIG.merge(config)
+    @api_version = config.delete(:api_version).freeze
+    @subdomain = config.delete(:api_subdomain).freeze
+
+    @logger = config.delete(:logger)
+
+    user_id = config.delete(:user_id)
+    encryption_key = config.delete(:encryption_key)
+    @auth = AuthHeader.new(user_id, encryption_key)
+
+    @wsdl = "http://app.marketo.com/soap/mktows/#{api_version}?WSDL".freeze
+    @endpoint = "https://#{subdomain}.mktoapi.com/soap/mktows/#{api_version}".freeze
+    @savon = Savon.client(config.merge(wsdl: wsdl, endpoint: endpoint))
+  end
+
+  # Indicates the presence of an error from the last call.
+  def error?
+    !!@error
+  end
+
+  ##
+  # :attr_reader: campaigns
+  # The MarketoAPI::Campaigns instance using this Client.
+
+  ##
+  # :attr_reader: leads
+  # The MarketoAPI::Leads instance using this Client.
+
+  ##
+  # :attr_reader: lists
+  # The MarketoAPI::Lists instance using this Client.
+
+  ##
+  # :attr_reader: mobjects
+  # The MarketoAPI::MObjects instance using this Client.
+
+  # Perform a SOAP API request with a properly formatted params message
+  # object.
+  #
+  # *Warning*: This method is for internal use by descendants of
+  # MarketoAPI::ClientProxy. It should not be called by external users.
+  def call(web_method, params) #:nodoc:
+    @error = nil
+    @savon.call(
+      web_method,
+      message: params,
+      soap_header: { 'ns1:AuthenticationHeader' => @auth.signature }
+    ).to_hash
+  rescue Exception => e
+    @error = e
+    @logger.log(e) if @logger
+    nil
+  end
+
+  private
+  # Implements the Marketo
+  # {Authentication Signature}[http://developers.marketo.com/documentation/soap/signature-algorithm/].
+  class AuthHeader #:nodoc:
+    DIGEST = OpenSSL::Digest.new('sha1')
+    private_constant :DIGEST
+
+    def initialize(user_id, encryption_key)
+      if user_id.nil? || encryption_key.nil?
+        raise ArgumentError, ":user_id and :encryption_key required"
+      end
+
+      @user_id = user_id
+      @encryption_key = encryption_key
+    end
+
+    attr_reader :user_id
+
+    # Compute the HMAC signature and return it.
+    def signature
+      time = Time.now
+      {
+        mktowsUserId:      user_id,
+        requestTimestamp:  time.to_s,
+        requestSignature:  hmac(time),
+      }
+    end
+
+    private
+    def hmac(time)
+      OpenSSL::HMAC.hexdigest(
+        DIGEST,
+        @encryption_key,
+        "#{time}#{user_id}"
+      )
+    end
+  end
+  private_constant :AuthHeader
+end
+
+require_relative 'campaigns'
+require_relative 'leads'
+require_relative 'lists'
+require_relative 'mobjects'

data/lib/marketo_api/client_proxy.rb

@@ -0,0 +1,104 @@
+require 'forwardable'
+
+# The ClientProxy is the base class for implementing Marketo APIs in a
+# fluent manner. When a descendant class is implemented, a method will be
+# added to MarketoAPI::Client based on the descendant class name that will
+# provide an initialized instance of the descendant class using the
+# MarketoAPI::Client instance.
+#
+# This base class does not provide any useful functionality for consumers of
+# MarketoAPI, and is primarily provided for common functionality.
+#
+# As an example, MarketoAPI::Client#campaigns was generated when
+# MarketoAPI::Campaigns was inherited from MarketoAPI::ClientProxy. It
+# returns an instance of MarketoAPI::Campaigns intialized with the
+# MarketoAPI::Client that generated it.
+class MarketoAPI::ClientProxy
+  extend Forwardable
+
+  class << self
+    # Generates a new method on MarketoAPI::Client based on the inherited
+    # class name.
+    def inherited(klass)
+      name = klass.name.split(/::/).last.downcase.to_sym
+
+      MarketoAPI::Client.class_eval <<-EOS
+        def #{name}
+          @#{name} ||= #{klass}.new(self)
+        end
+      EOS
+    end
+  end
+
+  def initialize(client)
+    @client = client
+  end
+
+  ##
+  # :attr_reader: error
+  #
+  # Reads the error attribute from the proxied client.
+
+  ##
+  # :method: error?
+  #
+  # Reads the presence of an error from the proxied client.
+
+  def_delegators :@client, :error, :error?
+
+  private
+  # Performs a SOAP call and extracts the result from a successful result.
+  #
+  # The Marketo SOAP API always returns results in a fairly deep structure.
+  # For example, the SOAP response for requestCampaign looks something like:
+  #
+  #     &lt;successRequestCampaign&gt;
+  #       &lt;result&gt;
+  #       &lt;/result&gt;
+  #     &lt;/successRequestCampaign&gt;
+  def call(method, param, &block)
+    extract_from_response(
+      @client.call(method, param),
+      :"success_#{method}",
+      :result,
+      &block
+    )
+  end
+
+  # Takes a parameter list and calls #transform_param on each parameter.
+  def transform_param_list(method, param_list)
+    method = :"params_for_#{method}"
+    param_list.map { |param|
+      transform_param(nil, param, method)
+    }.compact
+  end
+
+  # Takes a provided a parameter and transforms it. If the parameter is a
+  # Hash or +nil+, there is no transformation performed; if it responds to a
+  # method <tt>params_for_#{method}</tt>, that method is called to transform
+  # the object.
+  #
+  # If neither of these is true, an ArgumentError is raised.
+  def transform_param(method, param, override = nil)
+    method = if override
+               override
+             else
+               :"params_for_#{method}"
+             end
+    if param.kind_of? Hash or param.nil?
+      param
+    elsif param.respond_to? method
+      param.send(method)
+    else
+      raise ArgumentError, "Invalid parameter: #{param.inspect}"
+    end
+  end
+
+  # Given a response hash (which is deeply nested), follows the key path
+  # down.
+  def extract_from_response(response, *paths)
+    paths.each { |path| response &&= response[path] }
+    response = yield response if response and block_given?
+    response
+  end
+end

data/lib/marketo_api/lead.rb

@@ -0,0 +1,277 @@
+require 'forwardable'
+
+# An object representing a Marketo Lead record.
+class MarketoAPI::Lead
+  extend Forwardable
+  include Enumerable
+
+  NAMED_KEYS = { #:nodoc:
+    id:                         :IDNUM,
+    cookie:                     :COOKIE,
+    email:                      :EMAIL,
+    lead_owner_email:           :LEADOWNEREMAIL,
+    salesforce_account_id:      :SFDCACCOUNTID,
+    salesforce_contact_id:      :SFDCCONTACTID,
+    salesforce_lead_id:         :SFDCLEADID,
+    salesforce_lead_owner_id:   :SFDCLEADOWNERID,
+    salesforce_opportunity_id:  :SFDCOPPTYID
+  }.freeze
+
+  KEY_TYPES = MarketoAPI.freeze(*NAMED_KEYS.values) #:nodoc:
+  private_constant :KEY_TYPES
+
+  # The Marketo ID. This value cannot be set by consumers.
+  attr_reader :id
+  # The Marketo tracking cookie. Optional.
+  attr_accessor :cookie
+
+  # The attributes for the Lead.
+  attr_reader :attributes
+  # The types for the Lead attributes.
+  attr_reader :types
+  # The proxy object for this class.
+  attr_reader :proxy
+
+  def_delegators :@attributes, :[], :each, :each_pair, :each_key,
+    :each_value, :keys, :values
+
+  ##
+  # :method: [](hash)
+  # :call-seq:
+  #   lead[attribute_key]
+  #
+  # Looks up the provided attribute.
+
+  ##
+  # :method: each
+  # :call-seq:
+  #   each { |key, value| block }
+  #
+  # Iterates over the attributes.
+
+  ##
+  # :method: each_pair
+  # :call-seq:
+  #   each_pair { |key, value| block }
+  #
+  # Iterates over the attributes.
+
+  ##
+  # :method: each_key
+  # :call-seq:
+  #   each_key { |key| block }
+  #
+  # Iterates over the attribute keys.
+
+  ##
+  # :method: each_value
+  # :call-seq:
+  #   each_value { |value| block }
+  #
+  # Iterates over the attribute values.
+
+  ##
+  # :method: keys
+  # :call-seq:
+  #   keys() -> array
+  #
+  # Returns the attribute keys.
+
+  ##
+  # :method: values
+  # :call-seq:
+  #   values() -> array
+  #
+  # Returns the attribute values.
+
+  def initialize(options = {})
+    @id          = options[:id]
+    @attributes  = {}
+    @types       = {}
+    @foreign     = {}
+    self[:Email] = options[:email]
+    self.proxy   = options[:proxy]
+    yield self if block_given?
+  end
+
+  ##
+  # :method: []=(hash, value)
+  # :call-seq:
+  #   lead[key] = value -> value
+  #
+  # Looks up the provided attribute.
+  def []=(key, value)
+    @attributes[key] = value
+    @types[key] ||= infer_value_type(value)
+  end
+
+  # :attr_writer:
+  # :call-seq:
+  #   lead.proxy = proxy -> proxy
+  #
+  # Assign a proxy object. Once set, the proxy cannot be unset, but it can be
+  # changed.
+  def proxy=(value)
+    @proxy = case value
+             when nil
+               defined?(@proxy) && @proxy
+             when MarketoAPI::Leads
+               value
+             when MarketoAPI::ClientProxy
+               value.instance_variable_get(:@client).leads
+             when MarketoAPI::Client
+               value.leads
+             else
+               raise ArgumentError, "Invalid proxy type"
+             end
+  end
+
+  # :call-seq:
+  #   lead.foreign -> nil
+  #   lead.foreign(type, id) -> { type: type, id: id }
+  #   lead.foreign -> { type: type, id: id }
+  #
+  # Sets or returns the foreign system type and person ID.
+  def foreign(type = nil, id = nil)
+    @foreign = { type: type.to_sym, id: id } if type and id
+    @foreign
+  end
+
+  # :attr_reader: email
+  def email
+    self[:Email]
+  end
+
+  # :attr_writer: email
+  def email=(value)
+    self[:Email] = value
+  end
+
+  # Performs a Lead sync and returns the new Lead object, or +nil+ if the
+  # sync failed.
+  #
+  # Raises an ArgumentError if a proxy has not been configured with
+  # Lead#proxy=.
+  def sync
+    raise ArgumentError, "No proxy configured" unless proxy
+    proxy.sync(self)
+  end
+
+  # Performs a Lead sync and updates this Lead object in-place, or +nil+ if
+  # the sync failed.
+  #
+  # Raises an ArgumentError if a proxy has not been configured with
+  # Lead#proxy=.
+  def sync!
+    if lead = sync
+      @id      = lead.id
+      @cookie  = lead.cookie
+      @foreign = lead.foreign
+      @proxy   = lead.proxy
+      removed  = self.keys - lead.keys
+
+      lead.each_pair { |k, v|
+        @attributes[k] = v
+        @types[k]      = lead.types[k]
+      }
+
+      removed.each { |k|
+        @attributes.delete(k)
+        @types.delete(k)
+      }
+      self
+    end
+  end
+
+  # Returns a lead key structure suitable for use with
+  # MarketoAPI::Leads#get.
+  def params_for_get
+    self.class.key(:IDNUM, id)
+  end
+
+  # Returns the parameters required for use with MarketoAPI::Leads#sync.
+  def params_for_sync
+    {
+      return_lead: true,
+      marketo_cookie: cookie,
+      lead_record: {
+        email:                  email,
+        id:                     id,
+        foreign_sys_person_id:  foreign[:id],
+        foreign_sys_type:       foreign[:type],
+        lead_attribute_list: {
+          attribute: attributes.map { |key, value|
+            {
+              attr_name:   key.to_s,
+              attr_type:   types[key],
+              attr_value:  value
+            }
+          }
+        }
+      }.delete_if(&MarketoAPI::MINIMIZE_HASH)
+    }.delete_if(&MarketoAPI::MINIMIZE_HASH)
+  end
+
+  class << self
+    # Creates a new Lead from a SOAP response hash (from Leads#get,
+    # Leads#get_multiple, Leads#sync, or Leads#sync_multiple).
+    def from_soap_hash(hash) #:nodoc:
+      lead = new(id: hash[:id].to_i, email: hash[:email]) do |lr|
+        if type = hash[:foreign_sys_type]
+          lr.foreign(type, hash[:foreign_sys_person_id])
+        end
+        hash[:lead_attribute_list][:attribute].each do |attribute|
+          name = attribute[:attr_name].to_sym
+          lr.attributes[name] = attribute[:attr_value]
+          lr.types[name] = attribute[:attr_type]
+        end
+      end
+      yield lead if block_given?
+      lead
+    end
+
+    # Creates a new Lead key hash suitable for use in a number of Marketo
+    # API calls.
+    def key(key, value)
+      {
+        lead_key: {
+          key_type:   key_type(key),
+          key_value:  value
+        }
+      }
+    end
+
+    private
+    def key_type(key)
+      key = key.to_sym
+      res = if KEY_TYPES.include? key
+               key
+             else
+               NAMED_KEYS[key]
+             end
+      raise ArgumentError, "Invalid key #{key}" unless res
+      res
+    end
+  end
+
+  def ==(other)
+    id == other.id && cookie == other.cookie && foreign == other.foreign &&
+      attributes == other.attributes && types == other.types
+  end
+
+  def inspect
+    "#<#{self.class} id=#{id} cookie=#{cookie} foreign=#{foreign.inspect} attributes=#{attributes.inspect} types=#{types.inspect}>"
+  end
+
+  private
+  def infer_value_type(value)
+    case value
+    when Integer
+      'integer'
+    when Time, DateTime
+      'datetime'
+    else
+      'string'
+    end
+  end
+end