metaforce 0.5.3 → 1.0.0a

data/.gitignore

@@ -2,6 +2,7 @@
 .bundle
 Gemfile.lock
 pkg/*
+examples/tmp
 deploy.zip
 retrieve.zip
 test.rb

data/.rspec

@@ -0,0 +1 @@
+--colour

data/Gemfile

@@ -1,14 +1,4 @@
-source "http://rubygems.org"
-gem 'highline'
-gem 'thor'
+source :rubygems
 
 # Specify your gem's dependencies in metaforce.gemspec
 gemspec
-
-group :development do
-  gem "guard"
-  gem "guard-rspec"
-  gem "growl"
-  gem "yard"
-  gem "redcarpet"
-end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Eric J. Holmes
+
+MIT License
+
+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/README.md

@@ -1,139 +1,134 @@
-# Metaforce [![travis-ci](https://secure.travis-ci.org/ejholmes/metaforce.png)](https://secure.travis-ci.org/ejholmes/metaforce)
+# Metaforce
 
-Metaforce is a Ruby gem for interacting with the [Salesforce Metadata API](http://www.salesforce.com/us/developer/docs/api_meta/index.htm).
-The goal of this project is to make the [Migration Tool](http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_deploying_ant.htm) obsolete, favoring Rake over Ant.
+[![travis-ci](https://secure.travis-ci.org/ejholmes/metaforce.png)](https://secure.travis-ci.org/ejholmes/metaforce) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/ejholmes/metaforce) [![Dependency Status](https://gemnasium.com/ejholmes/metaforce.png)](https://gemnasium.com/ejholmes/metaforce)
+
+Metaforce is a Ruby gem for interacting with the Salesforce [Metadata](http://www.salesforce.com/us/developer/docs/api_meta/index.htm)
+and [Services](http://www.salesforce.com/us/developer/docs/api/index.htm) APIs.
 
 [Documentation](http://rubydoc.info/gems/metaforce/frames)
 
 ## Installation
+
 ```bash
 gem install metaforce
 ```
 
 ## Usage
-``` ruby
-client = Metaforce::Metadata::Client.new :username => 'username',
-    :password => 'password',
-    :security_token => 'security token')
-
-# Describe the metadata on the organization
-client.metadata_objects
-# => [{ :child_xml_names => "CustomLabel", :directory_name => "labels" ... }]
-
-# List all custom objects
-client.list(:custom_object)
-# => [{ :created_by_id => "005U0000000EGpcIAG", :created_by_name => "Eric Holmes", ... }]
-
-# Deploy metadata to the organization
-deployment = client.deploy(File.expand_path('path/to/src'))
-# => #<Metaforce::Transaction:0x00000102779bf8 @id="04sU0000000WNWoIAO" @type=:deploy> 
 
-# Get the result
-deployment.result
-# => { :id => "04sU0000000WNWoIAO", :messages => [{ :changed => true ... :success => true }
+### Initialization
 
-# Retrieve the metadata components specified in package.xml and unzip to the "retrieved" directory
-client.retrieve(File.expand_path('path/to/package.xml')).to('retrieved')
+#### Username and Password
 
-# Create a Visualforce page
-client.create_apex_page(:full_name => 'TestPage', :label => 'TestPage')
+To initialize a new client, you call `Metaforce.new` with a hash that specifies
+the `:username`, `:password`, and `:security_token`.
 
-# Update a Visualforce page
-client.update_apex_page('OldName', :full_name => 'NewName')
-
-# Delete a Visualforce page
-client.delete_apex_page('TestPage')
+```ruby
+client = Metaforce.new :username => 'username',
+  :password => 'password',
+  :security_token => 'security token'
 ```
 
-## Roadmap
-This gem is far from being feature complete. Here's a list of things that still
-need to be done.
-
-* Implement command line utility that can watch the directory and deploy when a
-  file changes.
-* Implement some helper methods for diffing metadata.
-* Ability to deploy directly from a git repository.
-* And some other stuff that I haven't quite thought of yet...
-
-## Contributing
-If you'd like to contribute code, please fork the repository and implement your
-feature on a new branch, then send me a pull request with a detailed
-description. Please provide applicable rspec specs.
-
-## Version History
-**0.5.3** (June 8, 2012)
-* Only trigger reauthentication if the response contains `INVALID_SESSION_ID`.
+#### Asynchronous Tasks
 
-**0.5.2** (June 8, 2012)
-* The services client now reauthentications on Savon::SOAP::Fault.
+Some calls to the SOAP API's are performed asynchronously (such as deployments),
+meaning the response needs to be polled for. Any call to the SOAP API's that
+are performed asynchronously will return a Metaforce::Job object, which can be used to
+subscribe to `on_complete` and `on_error` callbacks. The Metaforce::Job class
+will poll the status of the asynchronous job in a thread until it completes or
+fails.
 
-**0.5.1**
+* * *
 
-* Add thor integration.
+### deploy(path, options={})
 
-**0.5.0** (March 23, 2012)
+Takes a path (can be a path to a directory, or a zip file), and a set of
+[DeployOptions](http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_deploy.htm#deploy_options)
+and returns a `Metaforce::Job::Deploy`.
 
-* Implemented CRUD calls.
-
-**0.4.1** (March 8, 2012)
-
-* Bug fixes
+```ruby
+client.deploy(File.expand_path('./src'))
+  .on_complete { |job| puts "Finished deploy #{job.id}!" }
+  .on_error    { |job| puts "Something bad happened!" }
+  .perform
+#=> #<Metaforce::Job::Deploy @id='1234'>
+```
 
-**0.4.0** (March 2, 2012)
+* * *
 
-* Various bug fixes and improvements.
-* Removed DSL to focus on core functionality.
+### retrieve\_unpackaged(manifest, options={})
 
-**0.3.5** (February 11, 2012)
+Takes a manifest (`Metaforce::Manifest` or a path to a package.xml file) and a
+set of [RetrieveOptions](http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_retrieve_request.htm)
+and returns a `Metaforce::Job::Retrieve`.
 
-* Allow rake tasks to get credentials from a metaforce.yml file.
+```ruby
+manifest = Metaforce::Manifest.new(:custom_object => ['Account'])
+client.retrieve_unpackaged(manifest)
+  .extract_to('./tmp')
+  .perform
+#=> #<Metaforce::Job::Retrieve @id='1234'>
+```
 
-**0.3.4** (February 9, 2012)
+* * *
 
-* Add rake tasks.
+### create(type, metadata={})
 
-**0.3.3** (February 9, 2012)
+Takes a Symbol type and a Hash of [Metadata Attributes](http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_types_list.htm)
+and returns a `Metaforce::Job::CRUD`.
 
-* Added a logger for logging requests.
-* Allow api version to be set when calling `Metaforce::Metadata::Client.describe`.
+```ruby
+client.create(:apex_page, full_name: 'Foobar', content: 'Hello World!')
+  .on_complete { |job| puts "ApexPage created." }
+  .perform
+#=> #<Metaforce::Job::CRUD @id='1234'>
+```
 
-**0.3.2** (February 3, 2012)
+* * *
 
-* Improved documentation.
-* Added `.status` method to Transaction class.
+### update(type, current\_name metadata={})
 
-**0.3.1** (February 3, 2012)
+Takes a Symbol type, the current `full_name` of the resource, and a Hash of
+[Metadata Attributes](http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_types_list.htm)
+and returns a `Metaforce::Job::CRUD`.
 
-* Dynamically defined helper methods for .list (e.g. `client.list_apex_class`, `client.list_custom_object`).
-* The `Metaforce::Metadata::Client.describe` method now caches the results to minimize latency. `describe!`
-  can be used to force a refresh.
+```ruby
+client.update(:apex_page, 'Foobar', content: 'Hello World! Some new content!')
+  .on_complete { |job| puts "ApexPage updated." }
+  .perform
+#=> #<Metaforce::Job::CRUD @id='1234'>
+```
 
-**0.3.0.alpha** (January 29, 2012)
+* * *
 
-* Ability to retrieve metadata from an organization.
-* Added a DSL.
+### delete(type, \*args)
 
-**0.2.0.alpha** (January 28, 2012)
+Takes a Symbol type, and the `full_name` of a resource and returns a `Metaforce::Job::CRUD`.
 
-* Gem now supports interacting with the metadata api.
+```ruby
+client.delete(:apex_page, 'Foobar')
+  .on_complete { |job| puts "ApexPage deleted." }
+  .perform
+#=> #<Metaforce::Job::CRUD @id='1234'>
+```
 
-**0.1.0.alpha** (January 10, 2012)
+* * *
 
-* Ability to parse and modify package.xml files easily.
+### send\_email(options={})
 
-## License
-Copyright (C) 2012  Eric Holmes
+Sends a [SingleEmailMessage](http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_sendemail.htm) using Salesforce.
 
-This program is free software; you can redistribute it and/or
-modify it under the terms of the GNU General Public License
-as published by the Free Software Foundation; either version 2
-of the License, or (at your option) any later version.
+```ruby
+client.send_email(
+  to_addresses: ['foo@bar.com'],
+  subject: 'Hello World',
+  plain_text_body: 'Hello World'
+)
+```
 
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
+## Contributing
 
-You should have received a copy of the GNU General Public License
-along with this program; if not, write to the Free Software
-Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -1,18 +1,10 @@
+#!/usr/bin/env rake
 require "bundler/gem_tasks"
 
-task :default => :spec
+task :default => [:spec]
 
-desc "Run rspec specs"
-task :spec do
-  sh "bundle exec rspec spec"
-end
-
-desc "Start an irb session"
-task :console do
-  sh "irb -I lib -r metaforce"
-end
-
-desc "Build and publish gem on rubygems.org"
-task :publish do
-  sh "gem build metaforce.gemspec && gem push metaforce-*.gem"
+require 'rspec/core/rake_task'
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
 end

data/examples/example.rb

@@ -0,0 +1,51 @@
+require 'metaforce'
+
+# Run with: `USER=user PASS=pass TOKEN=securitytoken bundle exec ruby example.rb`
+
+Metaforce.configuration.log = false
+
+client = Metaforce.new :username => ENV['USER'],
+  :password => ENV['PASS'],
+  :security_token => ENV['TOKEN']
+
+Metaforce::Job.disable_threading!
+
+# Test sending an email.
+print 'send email to: '
+client.send_email(
+  to_addresses: [STDIN.gets.chomp],
+  subject: 'Test',
+  plain_text_body: 'Test'
+)
+
+# Test deployment.
+client.deploy('../spec/fixtures/payload.zip')
+  .on_complete { |job| puts "Deploy Completed: #{job.id}."}
+  .on_error    { |job| puts "Deploy Failed: #{job.id}."}
+  .perform
+
+# Test retrieve.
+manifest = Metaforce::Manifest.new(:custom_object => ['Account'])
+client.retrieve_unpackaged(manifest)
+  .on_complete { |job| puts "Retrieve Completed: #{job.id}."}
+  .on_error    { |job| puts "Retrieve Failed: #{job.id}."}
+  .extract_to('./tmp')
+  .perform
+
+# Test delete.
+client.delete(:apex_page, 'TestPage')
+  .on_complete { |job| puts "Delete Completed: #{job.id}."}
+  .on_error    { |job| puts "Delete Failed: #{job.id}."}
+  .perform
+
+# Test create.
+client.create(:apex_page, :full_name => 'TestPage', label: 'Test page', :content => '<apex:page>foobar</apex:page>')
+  .on_complete { |job| puts "Create Completed: #{job.id}."}
+  .on_error    { |job| puts "Create Failed: #{job.id}."}
+  .perform
+
+# Test update.
+client.update(:apex_page, 'TestPage', :full_name => 'TestPage', :label => 'Test page', :content => '<apex:page>hello world</apex:page>')
+  .on_complete { |job| puts "Update Completed: #{job.id}."}
+  .on_error    { |job| puts "Update Failed: #{job.id}."}
+  .perform

data/lib/metaforce/abstract_client.rb

@@ -0,0 +1,76 @@
+module Metaforce
+  class AbstractClient
+    class << self
+      # Internal
+      def endpoint(key)
+        define_method :endpoint do; @options[key] end
+      end
+
+      # Internal
+      def wsdl(wsdl)
+        define_method :wsdl do; wsdl end
+      end
+    end
+
+    # Public: Initialize a new client.
+    #
+    # options - A hash of options, which should have a :session_id key
+    def initialize(options={})
+      raise 'Please specify a hash of options' unless options.is_a?(Hash)
+      @options = options
+    end
+
+  private
+
+    # Internal: The Savon client to send SOAP requests with.
+    def client
+      @client ||= Savon.client(wsdl) do |wsdl|
+        wsdl.endpoint = endpoint
+      end.tap do |client|
+        client.config.soap_header = soap_headers
+        client.http.auth.ssl.verify_mode = :none
+      end
+    end
+
+    # Internal: Performs a SOAP request. If the session is invalid, it will
+    # attempt to reauthenticate by called the reauthentication handler if
+    # present.
+    def request(*args, &block)
+      begin
+        authenticate! unless session_id
+        _request(*args, &block)
+      rescue Savon::SOAP::Fault => e
+        raise e unless e.message =~ /INVALID_SESSION_ID/ && authentication_handler
+        authenticate!
+        _request(*args, &block)
+      end
+    end
+
+    def _request(*args, &block)
+      response = client.request(*args, &block)
+      Hashie::Mash.new(response.body)[:"#{args[0]}_response"].result
+    end
+
+    # Internal Calls the authentication handler, which should set @options to a new
+    # hash.
+    def authenticate!
+      authentication_handler.call(self, @options)
+    end
+
+    # A proc object that gets called when the client needs to reauthenticate.
+    def authentication_handler
+      Metaforce.configuration.authentication_handler
+    end
+
+    # Internal: Soap headers to set for authenticate.
+    def soap_headers
+      { 'ins0:SessionHeader' => { 'ins0:sessionId' => session_id } }
+    end
+
+    # Internal: The session id, which can be obtained by calling
+    # Metaforce.login or through OAuth.
+    def session_id
+      @options[:session_id]
+    end
+  end
+end

data/lib/metaforce/client.rb

@@ -0,0 +1,27 @@
+module Metaforce
+  class Client
+    def initialize(options)
+      @options = options
+    end
+
+    # Public: Used to interact with the Metadata API.
+    def metadata
+      @metadata ||= Metaforce::Metadata::Client.new(@options)
+    end
+
+    # Public: Used to interact with the Services API.
+    def services
+      @services ||= Metaforce::Services::Client.new(@options)
+    end
+
+    def method_missing(method, *args, &block)
+      if metadata.respond_to? method, false
+        metadata.send(method, *args, &block)
+      elsif services.respond_to? method, false
+        services.send(method, *args, &block)
+      else
+        super
+      end
+    end
+  end
+end

data/lib/metaforce/config.rb

@@ -41,26 +41,48 @@ module Metaforce
     attr_accessor :security_token
     # Set this to true if you're authenticating with a Sandbox instance.
     # Defaults to false.
-    attr_accessor :test
-    # Causes Metaforce::Transaction.result to loop until the transaction is
-    # complete. Defaults to true.
-    #
-    # If you want to do custom polling, set this to false.
-    #
-    # == Example
-    #
-    #   Metaforce.configuration.wait_until_done = false;
-    #
-    #   deploy = client.deploy File.expand_path("myeclipseproj")
-    #   begin; while !deploy.done?
-    #   deploy.result
-    attr_accessor :wait_until_done
+    attr_accessor :host
+    # A block that gets called when the session becomes invalid and the
+    # client needs to reauthenticate. Passes in the client and the client
+    # options. The block should set the options to a hash containing a valid
+    # session_id and service urls.
+    attr_accessor :authentication_handler
+
+    def api_version
+      @api_version ||= '26.0'
+    end
+
+    def host
+      @host ||= 'login.salesforce.com'
+    end
+
+    def authentication_handler
+      @authentication_handler ||= lambda { |client, options|
+        options.merge!(Metaforce.login(options))
+      }
+    end
+
+    def log=(log)
+      Savon.configure do |config|
+        config.log = log
+      end
+      HTTPI.log = log
+    end
+
+    def partner_wsdl
+      File.join(wsdl, 'partner.xml')
+    end
+
+    def metadata_wsdl
+      File.join(wsdl, 'metadata.xml')
+    end
+
+    def endpoint
+      "https://#{host}/services/Soap/u/#{api_version}"
+    end
 
-    def initialize
-      HTTPI.log        = false
-      @api_version     = "23.0"
-      @test            = false
-      @wait_until_done = true
+    def wsdl
+      File.expand_path("../../../wsdl/#{api_version}", __FILE__)
     end
 
     def logger

data/lib/metaforce/job/crud.rb

@@ -0,0 +1,13 @@
+module Metaforce
+  class Job::CRUD < Job
+    def initialize(client, method, args)
+      super(client)
+      @method, @args = method, args
+    end
+
+    def perform
+      @id = @client.send(@method, *@args).id
+      super
+    end
+  end
+end

data/lib/metaforce/job/deploy.rb

@@ -0,0 +1,87 @@
+module Metaforce
+  class Job::Deploy < Job
+
+    # Public: Instantiate a new deploy job.
+    #
+    # Examples
+    #
+    #   job = Metaforce::Job::Deploy.new(client, './path/to/deploy')
+    #   # => #<Metaforce::Job::Deploy @id=nil>
+    #
+    # Returns self.
+    def initialize(client, path, options={})
+      super(client)
+      @path, @options = path, options
+    end
+
+    # Public: Perform the job.
+    #
+    # Examples
+    #
+    #   job = Metaforce::Job::Deploy.new(client, './path/to/deploy')
+    #   job.perform
+    #   # => #<Metaforce::Job::Deploy @id='1234'>
+    #
+    # Returns self.
+    def perform
+      @id = client._deploy(payload, @options).id
+      super
+    end
+
+    # Public: Get the detailed status of the deploy.
+    #
+    # Examples
+    #
+    #   job.result
+    #   # => { :id => '1234', :success => true, ... }
+    #
+    # Returns the DeployResult (http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_deployresult.htm).
+    def result
+      client.status(id, :deploy)
+    end
+
+    # Public: Returns true if the deploy was successful.
+    #
+    # Examples
+    #
+    #   job.success?
+    #   # => true
+    # 
+    # Returns true or false based on the DeployResult.
+    def success?
+      result.success
+    end
+
+    # Public: Base64 encodes the contents of the zip file.
+    #
+    # Examples
+    #
+    #   job.payload
+    #   # => '<lots of base64 encoded content>'
+    #
+    # Returns the content of the zip file encoded to base64.
+    def payload
+      Base64.encode64(File.open(file, 'rb').read)
+    end
+
+  private
+
+    # Internal: Returns the path to the zip file.
+    def file
+      File.file?(@path) ? @path : zip_file
+    end
+
+    # Internal: Creates a zip file with the contents of the directory.
+    def zip_file
+      path = Dir.mktmpdir
+      File.join(path, 'deploy.zip').tap do |path|
+        Zip::ZipFile.open(path, Zip::ZipFile::CREATE) do |zip|
+          Dir["#{@path}/**/**"].each do |file|
+            zip.add(file.sub("#{File.dirname(@path)}/", ''), file)
+          end
+        end
+      end
+    end
+
+  end
+end