zuora-ruby 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f2609823dc2d907d854ef7c950b7a683f5795b2
-  data.tar.gz: 06c402c7774279668eb3891085eb3d9c7c72bf87
+  metadata.gz: 851d0abfff60f962e9325f3f2640b98e26757c9c
+  data.tar.gz: f45b66d5be58bef7ee808bb850d4ac3fd3a95990
 SHA512:
-  metadata.gz: 075799410c0f4b511ade42eded914a5d5287592297b77558f0ccd5f1b288893a31d9c160fb3a9952d34536228a656f7ab9c92f985e2e578bd8b945a6ba4e40b0
-  data.tar.gz: cd675321a91dfae484fc72447cca0378a74ab6b129b65c6d8e7c329d41cd688a70706d1624cc5b7951206c5417f17ba68f092c81c6b4435aa35f3a9ade545b19
+  metadata.gz: 98234b223c83ab68a662eb5dfd48f5fd827e69375cb142d101dc0570538212a674fbe9961710671644cee8494b14ab42e1b2b122c0bf22094a1a9fd54721626d
+  data.tar.gz: 1221da190beb70589a3260e0af9797d48f8b603a58e60ada3d5b6d4c803d3869c3761a540323fafb9376697a8121ff19a9e6a9647605eadfe17f2b61119dec1b

data/.hound.yml

@@ -0,0 +1,3 @@
+ruby:
+  enabled: true
+  config_file: .rubocop.yml

data/README.md

@@ -1,29 +1,67 @@
 [![Circle CI](https://circleci.com/gh/contactually/zuora-ruby.svg?style=shield&circle-token=808be5d625e91e331bedb37a2fe94412bb3bc15e)](https://circleci.com/gh/contactually/zuora-ruby)
-[![Code Climate](https://codeclimate.com/repos/569444dfa3d810003a00313f/badges/416bae00acf65d690efe/gpa.svg)](https://codeclimate.com/repos/569444dfa3d810003a00313f/feed)
-[![Test Coverage](https://codeclimate.com/repos/569444dfa3d810003a00313f/badges/416bae00acf65d690efe/coverage.svg)](https://codeclimate.com/repos/569444dfa3d810003a00313f/coverage)
+[![Code Climate](https://codeclimate.com/repos/5706a3fb4f15bd726100652d/badges/4e4615baaec76fd16535/gpa.svg)](https://codeclimate.com/repos/569444dfa3d810003a00313f/feed)
+[![Test Coverage](https://codeclimate.com/repos/5706a3fb4f15bd726100652d/badges/4e4615baaec76fd16535/coverage.svg)](https://codeclimate.com/repos/569444dfa3d810003a00313f/coverage)
 
-# Zuora SOAP API Client
+# Zuora SOAP and REST API Client
 
 ## Features
-* HTTP client to Zuora SOAP API
+* HTTP client to Zuora SOAP and REST API
 * Authentication and session storage
 * SOAP XML request constructors from Ruby data
 * Light validation of top-level forms; field-level validation delegated to Zuora's responses.
 
 ## Usage
 
-
 ### Client
 
-Create a client
+Creating a client to both SOAP and REST API is easy:
 ```ruby
 client = Zuora::Client.new(<username>, <password>)
 ```
+This will cache the login credentials (don't worry, they're excluded from being logged). Upon using methods requiring SOAP or REST client, that client is lazily authenticated against the respective API. The resulting session is cached and used in subsequent requests.
 
+It's possible to use the clients directly:
+```ruby
+soap_client = Zuora::Soap::Client.new(<username>, <password>)
+rest_client = Zuora::Rest::Client.new(<username>, <password>)
+```
 
-Execute a SOAP request. Currently only  `:create` and `:subscribe` are supported
+### SOAP Calls
+Soap calls are made using the `call!` method. The argument structure varies depending on the SOAP method. See specs for exact interfaces.
 
-#### Create Example
+```ruby
+client.call! :create, type: :Invoice, objects: [{...}, {...}]
+client.call! :update, type: :Invoice, objects: [{...}, {...}]
+client.call! :delete, type: :Invoice, ids: [{...}, {...}]
+client.call! :generate, objects: [{...}, {...}]
+client.call! :query, "SELECT Notes FROM Account WHERE id = '1'"
+client.call! :query, [:notes], :Account, {id: 1}
+client.call! :amend, 
+  amendments: {...}, 
+  amend_options: {...}, 
+  preview_options: {} 
+client.call! :subscribe,
+  payment_method: {...}
+  bill_to_contact: {...}
+  sold_to_contact: {...}
+  subscribe_options: {...}
+  subscription: {...}
+  rate_plan: {...}
+```
+
+SOAP requests return a `Zuora::Response` object that parses the XML response into Ruby data via the `#to_h` method. The raw request is available via the `#raw` method.
+
+### REST
+```ruby
+client.get('/rest/v1/accounts/1')
+client.delete('/rest/v1/accounts/1')
+client.post('/rest/v1/accounts', notes: 'hello')
+client.put('/rest/v1/accounts/1', id: 1, notes: 'world')
+```
+
+REST requests return a Farraday::Response object, which has a `body` and `status`. See [Farraday](https://github.com/lostisland/faraday) docs for details. 
+
+#### SOAP Create Example
 
  ```ruby
 response = client.call! :create,
@@ -101,7 +139,25 @@ response = client.call! :subscribe,
 ```
 
 # Changelog
-* **[0.1.0 - 2016-01-12]** Initial release 
+* **[0.5.0 2016-05-12]** Uniform REST and SOAP client
+  - Generalizes the client to work for both REST and SOAP APIs. In practice, both are useful to access the gamut  of Zuora's operations. SOAP is better for fine-grained control, while REST is larger-grained and shifts the burden of transactions onto Zuora for certain operations.
+  - Adds integration specs to cover REST GET, POST, PUT, DELETE
+  - Errors are thrown for unsuccessful responses
+  - Prevents credentials from being logged
+  - SOAP Query call: now with arity-1 and arity-3 versions, pass a ZOQL query as string or as data. See docs and specs for details.
+  - Add support for queryMore for result sets greater than 2000 in size
+
+* **[0.4.0 2016-02-10]** Improves interface and feedback loop between developer and Zuora servers.
+  - Allow flexible submission of parameters to the API.  Let Zuora's API handle validation instead of performing in the client.
+  - Adds integration specs to cover base functionality
+  - Adds exception raising to match servier-side exceptions such as missing required fields, invalid data, etc.
+
+* **[0.3.0 2016-1-28]** Focus on SOAP API, simplify client library feature set
+    - Implement SOAP API Client; it provides fuller functionality than REST 
+    - Focus on constructing + composing hash-like Ruby objects into XML SOAP requests 
+    - No object-level validations; relies on Zuora's own responses
+    - See integration specs for full interface
+
 * **[0.2.0] - 2016-01-14]** Models
      - Refactored client to clarify logic 
      - Replaces `ActiveRecord::Model` and `::Validations` with a base module that provides powerful and extensible facilities for modeling remote resources in Ruby. 
@@ -114,16 +170,7 @@ response = client.call! :subscribe,
      - Adds VCR for mocking out HTTP requests
      - Adds integration specs for `Subscribe` `create!` and `update!` and `Account` `create!` and `update!`
 
-* **[0.3.0 2016-1-28]** Focus on SOAP API, simpify client library feature set
-    - Implement SOAP API Client; it provides fuller functionality than REST 
-    - Focus on constructing + composing hash-like Ruby objects into XML SOAP requests 
-    - No object-level validations; relies on Zuora's own responses
-    - See integration specs for full interface
-    
-* **[0.4.0 2016-02-10]** Improves interface and feedback loop between developer and Zuora servers.
-  - Allow flexible submission of parameters to the API.  Let Zuora's API handle validation instead of performing in the client.
-  - Adds integration specs to cover base functionality
-  - Adds exception raising to match servier-side exceptions such as missing required fields, invalid data, etc.
+* **[0.1.0 - 2016-01-12]** Initial release 
 
 # Commit rights
 Anyone who has a patch accepted may request commit rights. Please do so inside the pull request post-merge.

data/lib/zuora.rb

@@ -21,12 +21,16 @@ module Zuora
     'xmlns:ns1' => 'http://api.zuora.com/',
     'xmlns:ns2' => 'http://object.api.zuora.com/'
   ).freeze
+
+  RETRY_WAITING_PERIOD = 120 # seconds
 end
 
 require_relative 'zuora/version'
 require_relative 'zuora/errors'
 require_relative 'zuora/utils/envelope'
 require_relative 'zuora/client'
+require_relative 'zuora/rest'
+require_relative 'zuora/soap'
 require_relative 'zuora/object'
 require_relative 'zuora/dispatcher'
 require_relative 'zuora/response'
@@ -39,5 +43,6 @@ require_relative 'zuora/calls/delete'
 require_relative 'zuora/calls/generate'
 require_relative 'zuora/calls/login'
 require_relative 'zuora/calls/query'
+require_relative 'zuora/calls/query_more'
 require_relative 'zuora/calls/subscribe'
 require_relative 'zuora/calls/update'

data/lib/zuora/calls/amend.rb

@@ -11,9 +11,11 @@ module Zuora
         lambda do |builder|
           builder[:api].amend do
             builder[:api].requests do
-              build_object builder, :amendments, :obj
-              build_object builder, :amend_options, :api
-              build_object builder, :preview_options, :api
+              Array.wrap(amendments).each do |amendment|
+                build_object builder, :amendments, amendment, :obj
+              end
+              build_object builder, :amend_options, amend_options, :api
+              build_object builder, :preview_options, preview_options, :api
             end
           end
         end
@@ -55,8 +57,7 @@ module Zuora
       # @param [Symbol] property_name - name of a property on this object
       # @param [Symbol] child_ns - namespace of child node fields
       # @return nil
-      def build_object(builder, property_name, child_ns)
-        object = send property_name
+      def build_object(builder, property_name, object, child_ns)
         fail 'Objects must respond to each' unless object.respond_to?(:each)
         object_name = Zuora::Utils::Envelope.to_zuora_key property_name
         builder[:api].send(object_name) do

data/lib/zuora/calls/query.rb

@@ -1,15 +1,54 @@
 module Zuora
   module Calls
     class Query < Hashie::Dash
-      def initialize(query_string)
-        @query_string = query_string
+      # This constructor has two arities.
+      # Arity 1: provide a raw ZOQL query string
+      # .new 'SELECT Id FROM Account WHERE Id = '1')
+
+      # Arity 2: provide simple query components
+      # .new [:id], :account, { :id => 1 }) will be transformed into query above
+
+      # @param [String|Array] select - query statement or field name sym array
+      # @param [Symbol|Nil] from -  table name symbol
+      # @param [Symbol|Nil] where - hash of equalities for where clauses
+      #    Operations: only = is supported
+      #    Custom field names are supported: some_field__c => SomeField__c
+      # @return [Zuora::Calls:Query]
+      def initialize(select, from = nil, where = nil)
+        @query_string = if select.is_a? Array
+                          query_to_string(select, from, where)
+                        else
+                          select
+                        end
       end
 
+      # @return [Callable]
       def xml_builder
         lambda do |builder|
           builder[:api].query { builder[:api].queryString(@query_string) }
         end
       end
+
+      private
+
+      # @param [Array] fields
+      # @param [Symbol] table
+      # @param [Hash] conditions
+      def query_to_string(fields, table, conditions)
+        fail 'Fields must be an Array' unless fields.is_a?(Array)
+        fail 'Table must respond to :to_sym' unless table.respond_to?(:to_sym)
+        fail 'Conditions must be Array' if fields && !fields.is_a?(Array)
+
+        key_fn = ->(key) { Zuora::Utils::Envelope.to_zuora_key(key) }
+
+        select = fields.map { |field| key_fn[field] }.join(', ').to_s
+        from = table.to_s
+        where = 'WHERE ' + conditions.map do |key, value|
+          "#{key_fn[key]} = '#{value}'"
+        end.join(' AND ') if conditions
+
+        "SELECT #{select} FROM #{from} #{where}".strip.squeeze(' ')
+      end
     end
   end
 end

data/lib/zuora/calls/query_more.rb

@@ -0,0 +1,22 @@
+module Zuora
+  module Calls
+    class QueryMore < Hashie::Dash
+      # After executing a query, often time a query_locator is returned when
+      # there are more records than Zuora can respond with in a single response.
+      # The default batch size is 2000.  You can use a combination of query and
+      # query_more calls to get large quantities of data.
+      # @param [String] query_locator
+      # @return [Zuora::Calls:Query]
+      def initialize(query_locator)
+        @query_locator = query_locator
+      end
+
+      # @return [Callable]
+      def xml_builder
+        lambda do |builder|
+          builder[:api].queryMore { builder[:api].queryLocator(@query_locator) }
+        end
+      end
+    end
+  end
+end

data/lib/zuora/client.rb

@@ -6,120 +6,52 @@ module Zuora
   class Client
     attr_accessor :session_token
 
-    SOAP_API_URI = '/apps/services/a/74.0'.freeze
-    SESSION_TOKEN_XPATH =
-      %w(//soapenv:Envelope soapenv:Body api:loginResponse
-         api:result api:Session).join('/').freeze
+    INSTANCE_VARIABLE_LOG_BLACKLIST = [:@username, :@password].freeze
 
-    # Creates a connection instance.
-    # Makes an initial SOAP request to fetch session token.
-    # Subsequent requests contain the authenticated session id
-    # in headers.
-    # @param [String] username
-    # @param [String] password
-    # @param [Boolean] sandbox
-    # @return [Zuora::SoapClient]
     def initialize(username, password, sandbox = true)
       @username = username
       @password = password
       @sandbox = sandbox
     end
 
-    # Makes auth request, handles response
-    # @return [Faraday::Response]
-    def authenticate!
-      auth_response = call! :login,
-        username: @username,
-        password: @password
-
-      handle_auth_response auth_response
-    rescue Object => e
-      raise Zuora::Errors::SoapConnectionError, e
+    # Delegate SOAP methods to SOAP client
+    def call!(*args)
+      soap_client.call!(*args)
     end
 
-    # Fire a request
-    # @param [Xml] body - an object responding to .xml
-    # @return [Zuora::Response]
-    def request!(body)
-      fail 'body must support .to_xml' unless body.respond_to? :to_xml
+    # Delegate REST methods to REST client
+    [:post, :put, :get, :delete].each do |method|
+      define_method(method) do |*args|
+        rest_client.send(method, *args)
+      end
+    end
 
-      raw_response = connection.post do |request|
-        request.url SOAP_API_URI
-        request.headers['Content-Type'] = 'text/xml'
-        request.body = body.to_xml
+    # Like Object.to_s, except excludes BLACKLISTed instance vars
+    def to_s
+      public_vars = instance_variables.reject do |var|
+        INSTANCE_VARIABLE_LOG_BLACKLIST.include? var
       end
 
-      response = Zuora::Response.new(raw_response)
+      public_vars.map! do |var|
+        "#{var}=\"#{instance_variable_get(var)}\""
+      end
 
-      response.handle_errors(response.to_h)
+      public_vars = public_vars.join(' ')
 
-      response
+      "<##{self.class}:#{object_id.to_s(8)} #{public_vars}>"
     end
 
-    # The primary interface via which users should make SOAP requests.
-    # client.call :create, object_name: :BillRun, data: {...}
-    # client.call :subscribe, account: {...}, sold_to_contact: {...}
-    # @param [Symbol] call_name - one of :create, :subscribe, :amend, :update
-    # @return [Faraday:Response] - response
-    def call!(call_name, *args)
-      factory = Zuora::Dispatcher.send call_name
-      xml_builder = factory.new(*args).xml_builder
-      request_data = envelope_for call_name, xml_builder
-      request! request_data
-    end
+    alias inspect to_s
 
     private
 
-    # Generate envelope for request
-    # @param [Symbol] call_name - one of the supported calls (see #call)
-    # @param [Callable] xml_builder_modifier - function taking a builder
-    # @return [Nokogiri::XML::Builder]
-    def envelope_for(call_name, xml_builder_modifier)
-      if call_name == :login
-        Zuora::Utils::Envelope.xml(nil, xml_builder_modifier)
-      else
-        Zuora::Utils::Envelope.authenticated_xml(@session_token) do |b|
-          xml_builder_modifier.call b
-        end
-      end
+    # Lazily connects SOAP / RESTS clients when needed; memoizes results
+    def soap_client
+      @soap_client ||= Zuora::Soap::Client.new(@username, @password, @sandbox)
     end
 
-    # Handle auth response, setting session
-    # @params [Faraday::Response]
-    # @return [Faraday::Response]
-    # @throw [Zuora::Errors::InvalidCredentials]
-    def handle_auth_response(response)
-      if response.raw.status == 200
-        @session_token = extract_session_token response
-      else
-        message = 'Unable to connect with provided credentials'
-        fail Zuora::Errors::InvalidCredentials, message
-      end
-      response
-    end
-
-    # Extracts session token from response and sets instance variable
-    # for use in subsequent requests
-    # @param [Faraday::Response] response - response to auth request
-    def extract_session_token(response)
-      response.to_h.envelope.body.login_response.result.session
-    end
-
-    # Initializes a connection using api_url
-    # @return [Faraday::Connection]
-    def connection
-      Faraday.new(api_url, ssl: { verify: false }) do |conn|
-        conn.adapter Faraday.default_adapter
-      end
-    end
-
-    # @return [String] - SOAP url based on @sandbox
-    def api_url
-      if @sandbox
-        'https://apisandbox.zuora.com/apps/services/a/74.0'
-      else
-        'https://api.zuora.com/apps/services/a/74.0'
-      end
+    def rest_client
+      @rest_client ||= Zuora::Rest::Client.new(@username, @password, @sandbox)
     end
   end
 end

data/lib/zuora/dispatcher.rb

@@ -27,6 +27,10 @@ module Zuora
         Zuora::Calls::Query
       end
 
+      def query_more
+        Zuora::Calls::QueryMore
+      end
+
       def delete
         Zuora::Calls::Delete
       end

data/lib/zuora/response.rb

@@ -27,7 +27,7 @@ module Zuora
         if value.is_a?(Hash)
           handle_errors(value)
         elsif value.is_a?(Array)
-          value.each { |v| handle_errors(v) }
+          value.each { |v| handle_errors(v) unless v.is_a?(String) }
         elsif error?(key, value)
           errors << value
         end

data/lib/zuora/rest.rb

@@ -0,0 +1,21 @@
+module Zuora
+  module Rest
+    API_URL = 'https://api.zuora.com/rest/v1/'.freeze
+    SANDBOX_URL = 'https://apisandbox-api.zuora.com/rest/v1/'.freeze
+
+    # Unable to connect. Check username / password
+    ConnectionError = Class.new StandardError
+
+    # Non-success response
+    class ErrorResponse < StandardError
+      attr_reader :response
+
+      def initialize(message = nil, response = nil)
+        super(message)
+        @response = response
+      end
+    end
+  end
+end
+
+require_relative 'rest/client'

data/lib/zuora/rest/client.rb

@@ -0,0 +1,132 @@
+# encoding: utf-8
+require 'faraday'
+require 'faraday_middleware'
+require 'json'
+
+module Zuora
+  module Rest
+    class Client
+      attr_reader :connection
+
+      # Creates a connection instance.
+      # Makes an initial HTTP request to fetch session token.
+      # Subsequent requests made with .get, .post, and .put
+      # contain the authenticated session id in their headers.
+      # @param [String] username
+      # @param [String] password
+      # @param [Boolean] sandbox
+      # @return [Zuora::Client] with .connection, .put, .post
+      def initialize(username, password, sandbox = false)
+        base_url = api_url sandbox
+        conn = connection base_url
+
+        response = conn.post do |req|
+          set_auth_request_headers! req, username, password
+        end
+
+        case response.status
+        when 200
+          @auth_cookie = response.headers['set-cookie'].split(' ')[0]
+          @connection = conn
+        when 429
+          sleep(Zuora::RETRY_WAITING_PERIOD)
+          return initialize(username, password, sandbox)
+        else
+          fail Zuora::Rest::ConnectionError, response.body['reasons']
+        end
+      end
+
+      # @param [String] url - URL of request
+      # @return [Faraday::Response] A response, with .headers, .status & .body
+      [:get, :delete].each do |method|
+        define_method(method) do |url|
+          response = @connection.send(method) do |req|
+            set_request_headers! req, url
+          end
+
+          # Handle rate limiting
+          return handle_rate_limiting(method, url) if response.status == 429
+
+          fail_or_response(response)
+        end
+      end
+
+      # @param [String] url - URL for HTTP POST / PUT request
+      # @param [Params] params - Data to be sent in request body
+      # @return [Faraday::Response] A response, with .headers, .status & .body
+      [:post, :put].each do |method|
+        define_method method do |url, params|
+          response = @connection.send(method) do |req|
+            set_request_headers! req, url
+            req.body = JSON.generate params
+          end
+
+          # Handle rate limiting
+          if response.status == 429
+            return handle_rate_limiting(method, url, params)
+          end
+
+          fail_or_response(response)
+        end
+      end
+
+      private
+
+      # @param [String] method
+      # @param [String] url
+      # @param [Hash] params
+      def handle_rate_limiting(method, url, params = nil)
+        sleep(Zuora::RETRY_WAITING_PERIOD)
+        if params.present?
+          send(method, url, params)
+        else
+          send(method, url)
+        end
+      end
+
+      # @param [Faraday::Response] response
+      # @throw [ErrorResponse] if unsuccessful
+      # @return [Faraday::Response]
+      def fail_or_response(response)
+        success = response.body['success'] && response.status == 200
+        fail(ErrorResponse.new('Non-200', response)) unless success
+        response
+      end
+
+      # @param [Faraday::Request] req - Faraday::Request builder
+      # @param [String] username
+      # @param [String] password
+      def set_auth_request_headers!(req, username, password)
+        req.url '/rest/v1/connections'
+        req.headers['apiAccessKeyId'] = username
+        req.headers['apiSecretAccessKey'] = password
+        req.headers['Content-Type'] = 'application/json'
+      end
+
+      # @param [Faraday::Request] request - Faraday Request builder
+      # @param [String] url - Relative URL for HTTP request
+      def set_request_headers!(request, url)
+        request.url url
+        request.headers['Content-Type'] = 'application/json'
+        request.headers['Cookie'] = @auth_cookie
+      end
+
+      # @param [String] url
+      # @return [Faraday::Client]
+      def connection(url)
+        Faraday.new(url, ssl: { verify: false }) do |conn|
+          conn.request :json
+          conn.response :json, content_type: /\bjson$/
+          conn.use :instrumentation
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # @param [Boolean] sandbox - Use the sandbox url?
+      # @return [String] url
+      def api_url(sandbox)
+        sandbox ? Zuora::Rest::SANDBOX_URL : Zuora::Rest::API_URL
+      end
+    end
+  end
+end

data/lib/zuora/soap.rb

@@ -0,0 +1,7 @@
+module Zuora
+  module Soap
+  end
+end
+
+require_relative 'soap/client'
+require_relative 'soap/z_object'

data/lib/zuora/soap/client.rb

@@ -0,0 +1,141 @@
+module Zuora
+  module Soap
+    class Client
+      attr_reader :session_token
+
+      SOAP_API_URI = '/apps/services/a/74.0'.freeze
+      SESSION_TOKEN_XPATH =
+        %w(//soapenv:Envelope soapenv:Body api:loginResponse
+           api:result api:Session).join('/').freeze
+
+      # Creates a connection instance.
+      # Makes an initial SOAP request to fetch session token.
+      # Subsequent requests contain the authenticated session id
+      # in headers.
+      # @param [String] username
+      # @param [String] password
+      # @param [Boolean] sandbox
+      # @return [Zuora::SoapClient]
+      def initialize(username, password, sandbox = true)
+        @sandbox = sandbox
+        authenticate!(username, password)
+      end
+
+      # Fire a request
+      # @param [Xml] body - an object responding to .xml
+      # @return [Zuora::Response]
+      def request!(body)
+        fail 'body must support .to_xml' unless body.respond_to? :to_xml
+
+        raw_response = connection.post do |request|
+          request.url SOAP_API_URI
+          request.headers['Content-Type'] = 'text/xml'
+          request.body = body.to_xml
+        end
+
+        # Handle rate limiting
+        return handle_rate_limiting(body) if raw_response.status == 429
+
+        response = Zuora::Response.new(raw_response)
+        begin
+          response.handle_errors(response.to_h)
+        rescue => e
+          return handle_lock_competition(e, body)
+        end
+        response
+      end
+
+      # The primary interface via which users should make SOAP requests.
+      # client.call :create, object_name: :BillRun, data: {...}
+      # client.call :subscribe, account: {...}, sold_to_contact: {...}
+      # @param [Symbol] call_name - one of :create, :subscribe, :amend, :update
+      # @return [Faraday:Response] - response
+      def call!(call_name, *args)
+        factory = Zuora::Dispatcher.send call_name
+        xml_builder = factory.new(*args).xml_builder
+        request_data = envelope_for call_name, xml_builder
+        request! request_data
+      end
+
+      private
+
+      # @param [Xml] body
+      # @return [Zuora::Response]
+      def handle_rate_limiting(body)
+        sleep(Zuora::RETRY_WAITING_PERIOD)
+        request!(body)
+      end
+
+      def handle_lock_competition(error, body)
+        if error.message =~ /(Operation failed due to a lock competition)/i
+          handle_rate_limiting(body)
+        else
+          fail error
+        end
+      end
+
+      # Makes auth request, handles response
+      # @return [Faraday::Response]
+      # @param [String] username
+      # @param [String] password
+      def authenticate!(username, password)
+        auth_response = call! :login,
+          username: username,
+          password: password
+
+        handle_auth_response auth_response
+      rescue Object => e
+        raise Zuora::Errors::SoapConnectionError, e
+      end
+
+      # Generate envelope for request
+      # @param [Symbol] call_name - one of the supported calls (see #call)
+      # @param [Callable] xml_builder_modifier - function taking a builder
+      # @return [Nokogiri::XML::Builder]
+      def envelope_for(call_name, xml_builder_modifier)
+        if call_name == :login
+          Zuora::Utils::Envelope.xml(nil, xml_builder_modifier)
+        else
+          Zuora::Utils::Envelope.authenticated_xml(@session_token) do |b|
+            xml_builder_modifier.call b
+          end
+        end
+      end
+
+      # Handle auth response, setting session
+      # @params [Faraday::Response]
+      # @return [Faraday::Response]
+      # @throw [Zuora::Errors::InvalidCredentials]
+      def handle_auth_response(response)
+        if response.raw.status == 200
+          @session_token = extract_session_token response
+        else
+          message = 'Unable to connect with provided credentials'
+          fail Zuora::Errors::InvalidCredentials, message
+        end
+        response
+      end
+
+      # Extracts session token from response and sets instance variable
+      # for use in subsequent requests
+      # @param [Faraday::Response] response - response to auth request
+      def extract_session_token(response)
+        response.to_h.envelope.body.login_response.result.session
+      end
+
+      # Initializes a connection using api_url
+      # @return [Faraday::Connection]
+      def connection
+        Faraday.new(api_url, ssl: { verify: false }) do |conn|
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # @return [String] - SOAP url based on @sandbox
+      def api_url
+        host_prefix = @sandbox ? 'sandbox' : ''
+        "https://api#{host_prefix}.zuora.com/apps/services/a/74.0"
+      end
+    end
+  end
+end

data/lib/zuora/soap/z_object.rb

@@ -0,0 +1,18 @@
+module Zuora
+  module Soap
+    class ZObject
+      extend Forwardable
+
+      attr_reader :type, :fields
+
+      # @params [Symbol] - name of ZObject
+      # @params [Hash] - a hash of fields
+      def initialize(type, fields)
+        @type = type
+        @fields = fields
+      end
+
+      def_delegators :@fields, :each, :map, :reduce, :inspect, :to_i
+    end
+  end
+end

data/lib/zuora/utils/envelope.rb

@@ -8,12 +8,8 @@ module Zuora
       def self.xml(header, body)
         Nokogiri::XML::Builder.new do |builder|
           builder[:soapenv].Envelope(Zuora::NAMESPACES) do
-            builder[:soapenv].Header do
-              header.call builder
-            end if header
-            builder[:soapenv].Body do
-              body.call builder
-            end if body
+            builder[:soapenv].Header { header.call builder } if header
+            builder[:soapenv].Body { body.call builder } if body
           end
         end
       end
@@ -26,24 +22,49 @@ module Zuora
         fail failure_message unless token.present?
 
         header = lambda do |builder|
-          builder[:api].SessionHeader do
-            builder[:api].session(token)
-          end
+          builder[:api].SessionHeader { builder[:api].session(token) }
           builder
         end
 
         xml(header, body)
       end
 
-      # Builds multiple fields
+      # Builds one field using key and value. Treats value differently:
+      #   - Hash: recursively builds fields
+      #   - ZObject: builds a nested z object, building fields inside
+      #   - Nil: does nothing
+      #   - Else: builds the field node
+      # @param [Nokogiri::XML::Builder] builder
+      # @param [Symbol] namespace
+      # @param [Hash] key
+      # @param [Hash|Zuora::Soap::ZObject|NilClass|Object] value
+      # @return nil
+      def self.build_field(builder, namespace, key, value)
+        zuora_field_name = to_zuora_key(key)
+        build_fields_thunk = -> { build_fields builder, namespace, value }
+        case value
+        when Hash
+          builder[namespace].send(zuora_field_name) { build_fields_thunk[] }
+        when Zuora::Soap::ZObject
+          zuora_type = to_zuora_key(value.type)
+          xsi = { 'xsi:type' => "obj:#{zuora_type}" }
+          builder[:api].send(zuora_field_name) do
+            builder[:api].send(zuora_type, xsi) { build_fields_thunk[] }
+          end
+        when NilClass
+        else
+          builder[namespace].send(zuora_field_name, value)
+        end
+      end
+
+      # Builds multiple fields in given object
       # @param [Nokogiri::XML::Builder] builder
       # @param [Symbol] namespace
       # @param [Hash] object
       # @return nil
       def self.build_fields(builder, namespace, object = {})
         object.each do |key, value|
-          zuora_field_name = to_zuora_key(key)
-          builder[namespace].send(zuora_field_name, value) unless value.nil?
+          build_field builder, namespace, key, value
         end
       end
 

data/lib/zuora/version.rb

@@ -1,3 +1,3 @@
 module Zuora
-  VERSION = '0.4.0'.freeze
+  VERSION = '0.5.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zuora-ruby
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Contactually Engineering
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-10 00:00:00.000000000 Z
+date: 2016-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -269,7 +269,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
 - ".gitignore"
+- ".hound.yml"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
@@ -289,6 +291,7 @@ files:
 - lib/zuora/calls/generate.rb
 - lib/zuora/calls/login.rb
 - lib/zuora/calls/query.rb
+- lib/zuora/calls/query_more.rb
 - lib/zuora/calls/subscribe.rb
 - lib/zuora/calls/update.rb
 - lib/zuora/calls/upsert.rb
@@ -297,6 +300,11 @@ files:
 - lib/zuora/errors.rb
 - lib/zuora/object.rb
 - lib/zuora/response.rb
+- lib/zuora/rest.rb
+- lib/zuora/rest/client.rb
+- lib/zuora/soap.rb
+- lib/zuora/soap/client.rb
+- lib/zuora/soap/z_object.rb
 - lib/zuora/utils/envelope.rb
 - lib/zuora/version.rb
 - zuora_ruby.gemspec