marketo-api-ruby 0.8

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NjY4NjRlOGQ0YjY2MWNmY2QwNDQyNmM3YTA2NTJlNzcxNmRiZTNiOA==
+  data.tar.gz: !binary |-
+    YWNhZjY4NGU3ZTE5YTVhZTY2Y2IyOTZmMGI4MTUyZTJmODg0MzFmZg==
+SHA512:
+  metadata.gz: !binary |-
+    MGYzYjBkODBjOTE1MDRmYmYxMmNhMjQyMDU0MmI2NGQwZTdhNGViM2Q1ODAx
+    NWU4NzJmN2YwOWEwYmRiM2EzMWQzZGRiNzRlNTZhMjNkZjY1ZmFkMTZiOGQz
+    YmVjYzJiYjMxZGY5ZTVlODRlODQwOGVmMTI1Y2RmNmQwMGNjYzM=
+  data.tar.gz: !binary |-
+    ZGNiMmEwYTU3NGE3MmE3NWE3NGI3Nzc5OWY3M2MxYWQwZDU1Njc3ZjRiZTc5
+    YTA0MDZiNTEyMTA2MjYzNjhjYTFiMWVlYjAzNmJjMzZhNmI0NGZhYTk3YTRh
+    N2NlY2Y3ZjM3ZDFmYWYzMTU1ZGI5NzNhMTZmY2I4YjcwMDNiNGE=

data.tar.gz.sig

@@ -0,0 +1,2 @@
+^ �޼p��'*h⻖�2xX��"8�
�Qb���a��ܑa�mٺ�$�s���OfB�~�.q_�`Ԗ=���!�$b�bGރ��n,lB�ndD�O��E��������G�z]}��P@��LM���n��rO�e�j�3�)��^'���2o�ɤmra
+�׆����C��>�C�nc*3�C~qs�j��
7�平��TXg�!)B��Hb�b��������a_ڌI�[���8��s��iG����.�c<t����

data/Contributing.rdoc

@@ -0,0 +1,65 @@
+== Contributing
+
+I value any contribution to marketo-api-ruby you can provide: a bug report, a
+feature request, or code contributions. Here are a few guidelines:
+
+* Code changes *will* *not* be accepted without tests. The test suite is
+  written with {Minitest}[https://github.com/seattlerb/minitest].
+* Match my coding style.
+* Use a thoughtfully-named topic branch that contains your change. Rebase your
+  commits into logical chunks as necessary.
+* Use {quality commit messages}[http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html].
+* Do not change the version number; when your patch is accepted and a release
+  is made, the version will be updated at that point.
+* Submit a GitHub pull request with your changes.
+* New or changed behaviours require new or updated documentation.
+
+=== Test Dependencies
+
+marketo-api-ruby uses Ryan Davis’s {Hoe}[https://github.com/seattlerb/hoe] to
+manage the release process, and it adds a number of rake tasks. You will mostly
+be interested in:
+
+    $ rake
+
+which runs the tests the same way that:
+
+    $ rake test
+    $ rake travis
+
+will do.
+
+To assist with the installation of the development dependencies for
+marketo-api-ruby, I have provided the simplest possible Gemfile pointing to the
+(generated) +marketo-api-ruby.gemspec+ file. This will permit you to do:
+
+    $ bundle install
+
+to get the development dependencies. If you aleady have +hoe+ installed, you
+can accomplish the same thing with:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs, and
+generate the RDoc.
+
+=== Workflow
+
+Here's the most direct way to get your work merged into the project:
+
+* Fork the project.
+* Clone down your fork (<tt>git clone git://github.com/<username>/marketo-api-ruby.git</tt>).
+* Create a topic branch to contain your change (<tt>git checkout -b my\_awesome\_feature</tt>).
+* Hack away, add tests. Not necessarily in that order.
+* Make sure everything still passes by running +rake+.
+* If necessary, rebase your commits into logical chunks, without errors.
+* Push the branch up (<tt>git push origin my\_awesome\_feature</tt>).
+* Create a pull request against ClearFit/marketo-api-ruby and describe what
+  your change does and the why you think it should be merged.
+
+=== Contributors
+
+* Austin Ziegler (@halostatue) created and maintains marketo-api-ruby for ClearFit.
+* James O'Brien (@jeob32) created
+  {marketo_gem}[https://github.com/Rapleaf/marketo_gem] for Rapleaf.
+* Eddie Siegel (@eddiesiegel)

data/Gemfile

@@ -0,0 +1,9 @@
+# -*- ruby -*-
+
+# NOTE: This file is present to keep Travis CI happy. Edits to it will not
+# be accepted.
+
+source "https://rubygems.org/"
+gemspec
+
+# vim: syntax=ruby

data/History.rdoc

@@ -0,0 +1,3 @@
+=== 0.8 / 2014-04-08
+
+* First release as marketo-api-ruby. Features a substantially restructured API.

data/Licence.rdoc

@@ -0,0 +1,24 @@
+== Licence
+
+This software is available under the terms of the MIT license.
+
+* Copyright 2014 ClearFit, Inc.
+* Copyright 2013 Rapleaft, Inc.
+
+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/Manifest.txt

@@ -0,0 +1,32 @@
+.gemtest
+Contributing.rdoc
+Gemfile
+History.rdoc
+Licence.rdoc
+Manifest.txt
+README.rdoc
+Rakefile
+lib/marketo-api-ruby.rb
+lib/marketo_api.rb
+lib/marketo_api/campaigns.rb
+lib/marketo_api/client.rb
+lib/marketo_api/client_proxy.rb
+lib/marketo_api/lead.rb
+lib/marketo_api/leads.rb
+lib/marketo_api/lists.rb
+lib/marketo_api/mobject.rb
+lib/marketo_api/mobjects.rb
+spec/marketo/authentication_header_spec.rb
+spec/marketo/client_spec.rb
+spec/marketo/lead_key_spec.rb
+spec/marketo/lead_record_spec.rb
+spec/spec_helper.rb
+test/marketo_api/test_campaigns.rb
+test/marketo_api/test_client.rb
+test/marketo_api/test_lead.rb
+test/marketo_api/test_leads.rb
+test/marketo_api/test_lists.rb
+test/marketo_api/test_mobject.rb
+test/marketo_api/test_mobjects.rb
+test/minitest_helper.rb
+test/test_marketo_api.rb

data/README.rdoc

@@ -0,0 +1,105 @@
+= marketo-api-ruby
+
+home :: https://github.com/ClearFit/marketo-api-ruby
+code :: https://github.com/ClearFit/marketo-api-ruby
+bugs :: https://github.com/ClearFit/marketo-api-ruby/issues
+rdoc :: https://rdoc.info/gems/marketo-api-ruby
+continuous integration :: {<img src="https://travis-ci.org/ClearFit/marketo-api-ruby.png" />}[https://travis-ci.org/ClearFit/marketo-api-ruby]
+test coverage :: {<img src="https://coveralls.io/repos/ClearFit/marketo-api-ruby/badge.png" alt="Coverage Status" />}[https://coveralls.io/r/ClearFit/marketo-api-ruby]
+
+== Description
+
+MarketoAPI (marketo-api-ruby) provides a native Ruby interface to the
+{Marketo SOAP API}[http://developers.marketo.com/documentation/soap/], using
+{savon}[https://github.com/savonrb/savon]. While understanding the Marketo SOAP
+API is necessary for using marketo-api-ruby, it is an explicit goal that
+working with MarketoAPI not feel like working with a hinky Java port.
+
+This is release 0.8, targeting Marketo API version
+{2.3}[http://app.marketo.com/soap/mktows/2_3?WSDL].
+
+=== Features/Problems
+
+The marketo-api-ruby implementation of the Marketo SOAP API is incomplete, but
+is scheduled to be complete against Marketo SOAP API 2.3 for the version 1.0
+release; this will take some time.
+
+- Marketo Object (MObject) operations are 80% implemented.
+  - Not implemented: +syncMObjects+
+  - Improvements will be made to the criteria-building interface and the
+    association-building interface.
+- Marketo Custom Object operations are not yet implemented.
+- Marketo Lead operations are 37% implemented.
+  - Not implemented: +getMultipleLeads+, +mergeLeads+, +getLeadActivity+,
+    +getLeadChanges+
+- Marketo Campaign operations are 90% implemented.
+  - The +requestCampaign+ API is currently awkward around managing program
+    tokens (+programTokenList+ in the SOAP API).
+  - The +scheduleCampaign+ API is currently awkward around managing program
+    tokens (+programTokenList+ in the SOAP API).
+- Marketo List opertions are 100% implemented.
+
+== Synopsis
+
+    require 'marketo_api' # Only required if not loaded by Bundler
+    marketo = MarketoAPI.client(
+      api_subdomain:  '123-ABC-456',
+      user_id:        'my-api-user-id',
+      encryption_key: 'my-api-encryption-key'
+    )
+
+    # Get a lead by email, and sync it back to Marketo.
+    lead = marketo.leads.get_by_email('mork@ork.com')
+    lead.email = 'mindy@ork.com'
+    lead.sync!
+
+    # Get campaigns for marketo (MKTOWS)
+    puts marketo.campaigns.for_marketo
+
+    # Delete Opportunity 75.
+    marketo.mobjects.delete MarketoAPI::MObject.opportunity(75)
+
+    # Get all Marketo programs 
+
+== Install
+
+Add to your application's Gemfile:
+
+    gem 'marketo-api-ruby'
+
+Or install manually:
+
+    gem install marketo-api-ruby
+
+== Developers
+
+After checking out the source, run:
+
+  $ rake newb
+
+This task will install any missing dependencies, run the tests/specs,
+and generate the RDoc.
+
+== marketo-api-ruby Modified Semantic Versioning
+
+The marketo-api-ruby library tracks an externally versioned API; this is not
+fully compatible with all aspects of {Semantic Versioning}[http://semver.org/]. 
+
+1. MAJOR versions will be updated when targeting a new major version of the
+   Marketo API, if Marketo makes incompatible changes to its API in minor
+   versions, *or* when incompatible marketo-api-ruby API changes are made. The
+   release notes will identify the cause of the update.
+2. MINOR versions will be updated when targeting a new minor version of the
+   Marketo API (e.g., Marketo version 2.2 to 2.3).
+3. PATCH version when backwards-compatible bug fixes are made.
+
+Additionally, each release will clearly identify which Marketo API it targets
+as its baseline. If a release is made without a PATCH level, it can be assumed
+to be zero.
+
+In practical terms, MAJOR versions will only be updated if you cannot use an
+earlier API version for an existing query (such as +Marketo::Lead#sync+).
+
+:include: Contributing.rdoc
+
+:include: Licence.rdoc

data/Rakefile

@@ -0,0 +1,65 @@
+# -*- ruby -*-
+
+require "rubygems"
+require "hoe"
+
+Hoe.plugin :doofus
+Hoe.plugin :gemspec2
+Hoe.plugin :git
+Hoe.plugin :heroku
+Hoe.plugin :minitest
+Hoe.plugin :travis
+Hoe.plugin :email unless ENV['CI'] or ENV['TRAVIS']
+
+spec = Hoe.spec "marketo-api-ruby" do
+  developer('Austin Ziegler', 'halostatue@gmail.com')
+  self.need_tar = false
+  self.require_ruby_version '>= 1.9.2'
+
+  license 'MIT'
+
+  self.history_file = 'History.rdoc'
+  self.readme_file = 'README.rdoc'
+  self.extra_rdoc_files = FileList["*.rdoc"].to_a
+
+  self.extra_deps << ['savon', '~> 2.4']
+
+  self.extra_dev_deps << ['hoe-doofus', '~> 1.0']
+  self.extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
+  self.extra_dev_deps << ['hoe-git', '~> 1.6']
+  self.extra_dev_deps << ['hoe-rubygems', '~> 1.0']
+  self.extra_dev_deps << ['hoe-travis', '~> 1.2']
+  self.extra_dev_deps << ['minitest', '~> 5.3']
+  self.extra_dev_deps << ['rake', '~> 10.0']
+  self.extra_dev_deps << ['simplecov', '~> 0.7']
+  self.extra_dev_deps << ['coveralls', '~> 0.7']
+end
+
+namespace :test do
+  desc "Submit test coverage to Coveralls"
+  task :coveralls do
+    spec.test_prelude = [
+      'require "psych"',
+      'require "simplecov"',
+      'require "coveralls"',
+      'SimpleCov.formatter = Coveralls::SimpleCov::Formatter',
+      'SimpleCov.start("test_frameworks") { command_name "Minitest" }',
+      'gem "minitest"'
+    ].join('; ')
+    Rake::Task['test'].execute
+  end
+
+  desc "Generate a test coverage report"
+  task :coverage do
+    spec.test_prelude = [
+      'require "simplecov"',
+      'SimpleCov.start("test_frameworks") { command_name "Minitest" }',
+      'gem "minitest"'
+    ].join('; ')
+    Rake::Task['test'].execute
+  end
+end
+
+Rake::Task['travis'].prerequisites.replace(%w(test:coveralls))
+
+# vim: syntax=ruby

data/lib/marketo-api-ruby.rb

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

data/lib/marketo_api.rb

@@ -0,0 +1,39 @@
+# MarketoAPI (marketo-api-ruby) provides a native Ruby interface to the
+# {Marketo SOAP API}[http://developers.marketo.com/documentation/soap/],
+# using {savon}[https://github.com/savonrb/savon].
+#
+# == Synopsis
+#
+#   require 'marketo_api'
+module MarketoAPI
+  VERSION = "0.8"
+
+  MINIMIZE_HASH = ->(k, v) { #:nodoc:
+    v.nil? or (v.respond_to?(:empty?) and v.empty?)
+  }
+
+  class << self
+    # Create a new MarketoAPI::Client, essentially an alias for
+    # MarketoAPI::Client.new.
+    def client(config = {})
+      MarketoAPI::Client.new(config)
+    end
+
+    def array(object) # :nodoc:
+      case object
+      when Hash
+        [ object ]
+      when Array
+        object
+      else
+        Kernel.Array(object)
+      end
+    end
+
+    def freeze(*args) # :nodoc:
+      args.each(&:freeze).freeze
+    end
+  end
+end
+
+require 'marketo_api/client'

data/lib/marketo_api/campaigns.rb

@@ -0,0 +1,194 @@
+require_relative 'client_proxy'
+
+# Implements Campaign-related calls for Marketo.
+#
+# === Sources
+#
+# Campaigns have a source, which the Marketo SOAP API provides as +MKTOWS+
+# and +SALES+. MarketoAPI provides these values as the friendlier values
+# +marketo+ and +sales+, but accepts the standard Maketo SOAP API
+# enumeration values.
+class MarketoAPI::Campaigns < MarketoAPI::ClientProxy
+  SOURCES = { #:nodoc:
+    marketo: :MKTOWS,
+    sales:   :SALES,
+  }.freeze
+  private_constant :SOURCES
+
+  ENUMS = MarketoAPI.freeze(*SOURCES.values) #:nodoc:
+  private_constant :ENUMS
+
+  # Implements
+  # {+getCampaignsForSource+}[http://developers.marketo.com/documentation/soap/getcampaignsforsource/].
+  #
+  # If possible, prefer the generated methods #for_marketo and #for_sales.
+  #
+  # :call-seq:
+  #   for_source(source)
+  #   for_source(source, name)
+  #   for_source(source, name, exact_name)
+  def for_source(source, name = nil, exact_name = nil)
+    call(
+      :get_campaigns_for_source,
+      {
+        source:      resolve_source(source),
+        name:        name,
+        exact_name:  exact_name
+      }.delete_if(&MarketoAPI::MINIMIZE_HASH)
+    )
+  end
+
+  ##
+  # :method: for_marketo
+  #
+  # Implements +getCampaignsForSource+ for the +marketo+ source; a
+  # specialization of #for_source.
+  #
+  # :call-seq:
+  #   for_marketo()
+  #   for_marketo(name)
+  #   for_marketo(name, exact_name)
+
+  ##
+  # :method: for_sales
+  #
+  # Implements +getCampaignsForSource+ for the +sales+ source; a
+  # specialization of #for_source.
+  #
+  # :call-seq:
+  #   for_sales()
+  #   for_sales(name)
+  #   for_sales(name, exact_name)
+
+  # Implements
+  # {+requestCampaign+}[http://developers.marketo.com/documentation/soap/requestcampaign/].
+  #
+  # === Parameters
+  #
+  # +source+::         Required. The source of the campaign.
+  # +leads+::          Required. An array of Lead objects or lead keys. If
+  #                    both +leads+ and +lead+ are provided, they will be
+  #                    merged.
+  # +lead+::           An alias for +leads+.
+  # +campaign_id+::    The campaign ID to request for the +lead+ or +leads+.
+  #                    Required if +campaign_name+ or +program_name+ are not
+  #                    provided.
+  # +campaign_name+::  The campaign name to request for the +lead+ or
+  #                    +leads+. Required if +campaign_id+ or +program_name+
+  #                    are not provided.
+  # +program_name+::   The program name to request for the +lead+ or
+  #                    +leads+. Required if +campaign_id+ or +campaign_name+
+  #                    are not provided, or if +program_tokens+ are
+  #                    provided.
+  # +program_tokens+:: An array of program tokens in the form:
+  #                    <tt>{ attrib: { name: name, value: value } }</tt>
+  #                    This will be made easier to manage in the future.
+  #
+  # If possible, prefer #request_marketo and #request_sales.
+  #
+  # :call-seq:
+  #   request(options)
+  def request(options = {})
+    source = options.fetch(:source) { :MKTOWS }
+    leads = MarketoAPI.array(options.delete(:leads)) +
+      MarketoAPI.array(options.delete(:lead))
+    if leads.empty?
+      raise ArgumentError, ':lead or :leads must be provided'
+    end
+
+    valid_id = options.has_key?(:campaign_id) ||
+      options.has_key?(:campaign_name) || options.has_key?(:program_name)
+    unless valid_id
+      raise ArgumentError,
+        ':campaign_id, :campaign_name, or :program_name must be provided'
+    end
+
+    if options.has_key?(:campaign_id) && options.has_key?(:campaign_name)
+      raise ArgumentError,
+        ':campaign_id and :campaign_name are mutually exclusive'
+    end
+
+    if (tokens = options.delete(:program_tokens)) && !tokens.empty?
+      if !options[:program_name]
+        raise KeyError,
+          ':program_name must be provided when using :program_tokens'
+      end
+    end
+
+    call(
+      :request_campaign,
+      options.merge(
+        source:              resolve_source(source),
+        lead_list:           transform_param_list(:get, leads),
+        program_token_list:  tokens
+      ).delete_if(&MarketoAPI::MINIMIZE_HASH)
+    )
+  end
+
+  ##
+  # :method: request_marketo
+  #
+  # Implements +getCampaignsForSource+ for the +marketo+ source; a
+  # specialization of #request.
+  #
+  # :call-seq:
+  #   request_marketo(options)
+
+  ##
+  # :method: request_sales
+  #
+  # Implements +getCampaignsForSource+ for the +sales+ source; a
+  # specialization of #request.
+  #
+  # :call-seq:
+  #   request_sales(options)
+
+  # Implements
+  # {+scheduleCampaign+}[http://developers.marketo.com/documentation/soap/schedulecampaign/].
+  #
+  # === Optional Parameters
+  #
+  # +run_at+::          The time to run the scheduled campaign.
+  # +program_tokens+::  An array of program tokens in the form:
+  #                     <tt>{ attrib: { name: name, value: value } }</tt>
+  #                     This will be made easier to manage in the future.
+  #
+  # +source+ must be +marketo+ or +sales+ or the equivalent enumerated
+  # values from the SOAP environment (+MKTOWS+ or +SALES+).
+  #
+  # :call-seq:
+  #   schedule(program_name, campaign_name, options = {})
+  def schedule(program_name, campaign_name, options = {})
+    call(
+      :schedule_campaign,
+      {
+        program_name: program_name,
+        campaign_name: campaign_name,
+        campaign_run_at: options[:run_at],
+        program_token_list: options[:program_tokens]
+      }.delete_if(&MarketoAPI::MINIMIZE_HASH)
+    )
+  end
+
+  SOURCES.each_pair { |source, enum|
+    define_method(:"for_#{source}") do |name = nil, exact_name = nil|
+      for_source(enum, name, exact_name)
+    end
+
+    define_method(:"request_#{source}") do |options = {}|
+      request(options.merge(source: enum))
+    end
+  }
+
+  private
+  def resolve_source(source)
+    source = source.to_sym
+    res = if ENUMS.include? source
+            source
+          else
+            SOURCES[source]
+          end
+    raise ArgumentError, "Invalid source #{source}" unless res
+    res
+  end
+end