metaforce-beta 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 48b04d4fa24a6113f10acea5b0966fedab064370
+  data.tar.gz: b2b3515deac5b9312b15c506eb5f58b461fb414b
+SHA512:
+  metadata.gz: 02a9b697f81eae485027dc7a9f914f269da44df68fb1b8b7a03d68b2a2fdc5ba69ae6c395761647b0cad3d8198f392478f3d3f68e206ca017641e6f5459878ff
+  data.tar.gz: f951e172ef8f8bd1364e9a830e9248cf93401a6c5aec030510cec0214fc99fae6946eefa0505553f655c943f5f7c5c6f28e1a035efb4bd9a1423fdd4b709993f

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+examples/tmp
+deploy.zip
+retrieve.zip
+test.rb
+.metaforce.yml

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - ruby-head
+  - jruby-head
+script: bundle exec rspec spec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in metaforce.gemspec
+gemspec

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

@@ -0,0 +1,193 @@
+# Metaforce
+
+[![Build Status](https://travis-ci.org/ejholmes/metaforce.png?branch=master)](https://travis-ci.org/ejholmes/metaforce) [![Code Climate](https://codeclimate.com/github/ejholmes/metaforce.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
+
+Add this line to your application's Gemfile:
+
+    gem 'metaforce'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install metaforce
+
+## Usage
+
+### Initialization
+
+#### Username and Password
+
+To initialize a new client, you call `Metaforce.new` with a hash that specifies
+the `:username`, `:password`, and `:security_token`.
+
+```ruby
+client = Metaforce.new :username => 'username',
+  :password => 'password',
+  :security_token => 'security token'
+```
+
+Or you can specify the username, password and security token with environment
+variables:
+
+```bash
+export SALESFORCE_USERNAME="username"
+export SALESFORCE_PASSWORD="password"
+export SALESFORCE_SECURITY_TOKEN="security token"
+```
+
+```ruby
+client = Metaforce.new
+```
+
+#### Asynchronous Tasks
+
+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.
+
+* * *
+
+### deploy(path, options={})
+
+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`.
+
+```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'>
+```
+
+* * *
+
+### retrieve\_unpackaged(manifest, options={})
+
+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`.
+
+```ruby
+manifest = Metaforce::Manifest.new(:custom_object => ['Account'])
+client.retrieve_unpackaged(manifest)
+  .extract_to('./tmp')
+  .perform
+#=> #<Metaforce::Job::Retrieve @id='1234'>
+```
+
+* * *
+
+### create(type, metadata={})
+
+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`.
+
+```ruby
+client.create(:apex_page, full_name: 'Foobar', content: 'Hello World!')
+  .on_complete { |job| puts "ApexPage created." }
+  .perform
+#=> #<Metaforce::Job::CRUD @id='1234'>
+```
+
+* * *
+
+### update(type, current\_name metadata={})
+
+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`.
+
+```ruby
+client.update(:apex_page, 'Foobar', content: 'Hello World! Some new content!')
+  .on_complete { |job| puts "ApexPage updated." }
+  .perform
+#=> #<Metaforce::Job::CRUD @id='1234'>
+```
+
+* * *
+
+### delete(type, \*args)
+
+Takes a Symbol type, and the `full_name` of a resource and returns a `Metaforce::Job::CRUD`.
+
+```ruby
+client.delete(:apex_page, 'Foobar')
+  .on_complete { |job| puts "ApexPage deleted." }
+  .perform
+#=> #<Metaforce::Job::CRUD @id='1234'>
+```
+
+* * *
+
+### send\_email(options={})
+
+Sends a [SingleEmailMessage](http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_sendemail.htm) using Salesforce.
+
+```ruby
+client.send_email(
+  to_addresses: ['foo@bar.com'],
+  subject: 'Hello World',
+  plain_text_body: 'Hello World'
+)
+```
+
+If you're using Rails, check out the [metaforce-delivery\_method](https://github.com/ejholmes/metaforce-delivery_method)
+gem, which allows you to use Salesforce as the delivery mechanism for sending
+emails.
+
+## Command-line
+
+Metaforce also comes with a handy command line utility that can deploy and retrieve
+code from Salesforce. It also allows you to watch a directory and deploy when
+anything changes.
+
+When you deploy, it will also run all tests and provide you with a report,
+similar to rspec.
+
+```bash
+$ metaforce deploy ./src
+Deploying: ./src
+```
+
+```bash
+$ metaforce watch ./src
+Watching: ./src
+```
+
+```bash
+$ metaforce retrieve ./src
+Retrieving: ./src/package.xml
+
+$ metaforce retrieve ./src/package.xml ./other-location
+Retrieving: ./src/package.xml
+```
+
+### .metaforce.yml
+
+The metaforce command will pull it's configuration from a `.metaforce.yml`
+file, if present. You can provide options for multiple environments, then use
+the `-e` swtich on the command line to use an environment. See the
+[examples](examples) directory for an example.
+
+## Contributing
+
+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

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+task :default => [:spec]
+
+require 'rspec/core/rake_task'
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end

data/bin/metaforce

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'bundler/setup'
+require 'metaforce'
+
+begin
+  require 'metaforce/cli'
+  Metaforce::CLI.start
+rescue Interrupt => e
+  puts "\nQuitting..."
+  exit 1
+rescue SystemExit => e
+  exit e.status
+end

data/examples/example.rb

@@ -0,0 +1,52 @@
+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: '; email = STDIN.gets.chomp
+client.send_email(
+  to_addresses: [email],
+  subject: 'Test',
+  plain_text_body: 'Test'
+) if email
+
+# 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 deployment.
+client.deploy('./tmp')
+  .on_complete { |job| puts "Deploy Completed: #{job.id}. #{job.result}"}
+  .on_error    { |job| puts "Deploy Failed: #{job.id}."}
+  .on_poll     { |job| puts "Deploy: Polled status for #{job.id}."}
+  .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.rb

@@ -0,0 +1,34 @@
+require 'savon'
+require 'hashie'
+require 'active_support'
+require 'active_support/core_ext'
+
+require 'metaforce/version'
+require 'metaforce/config'
+require 'metaforce/job'
+require 'metaforce/abstract_client'
+require 'metaforce/services/client'
+require 'metaforce/metadata/client'
+
+module Metaforce
+  autoload :Manifest, 'metaforce/manifest'
+  autoload :Login,    'metaforce/login'
+  autoload :Client,   'metaforce/client'
+
+  class << self
+    # Public: Initializes instances of the metadata and services api clients
+    # and provides helper methods for deploying and retrieving code.
+    def new(*args)
+      Client.new(*args)
+    end
+
+    # Performs a login and retrurns the session
+    def login(options={})
+      options = HashWithIndifferentAccess.new(options)
+      username       = options.fetch(:username, ENV['SALESFORCE_USERNAME'])
+      password       = options.fetch(:password, ENV['SALESFORCE_PASSWORD'])
+      security_token = options.fetch(:security_token, ENV['SALESFORCE_SECURITY_TOKEN'])
+      Login.new(username, password, security_token).login
+    end
+  end
+end

data/lib/metaforce/abstract_client.rb

@@ -0,0 +1,86 @@
+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)
+      authenticate! unless session_id
+      retries = authentication_retries
+      begin
+        perform_request(*args, &block)
+      rescue Savon::SOAP::Fault => e
+        if e.message =~ /INVALID_SESSION_ID/ && authentication_handler && retries > 0
+          authenticate!
+          retries -= 1
+          retry
+        end
+        raise
+      end
+    end
+
+    def perform_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!
+      options = authentication_handler.call(self, @options)
+      @options.merge!(options)
+      client.config.soap_header = soap_headers
+    end
+
+    # A proc object that gets called when the client needs to reauthenticate.
+    def authentication_handler
+      Metaforce.configuration.authentication_handler
+    end
+
+    def authentication_retries
+      3
+    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