zuora-ruby 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 59ac3797046acdb3f30dbd498d3f5368024d6c8f
-  data.tar.gz: c747cfe5f6c0e2dfeeb46da7a0279761e201ecba
+  metadata.gz: 7f2609823dc2d907d854ef7c950b7a683f5795b2
+  data.tar.gz: 06c402c7774279668eb3891085eb3d9c7c72bf87
 SHA512:
-  metadata.gz: a2e9865623c907ad008b942f39fb831979f6fe65f8b7d159f4176ae074ea41867e38883d77e891922e1e3e70da7685a3ad617dbe9cbf6aedfefceba8513f2b56
-  data.tar.gz: ded935331529eecc8ce365652be19e7fadb252c949e919d7e0bca07af74211d7f1cf5cc4264c3dd2d721bfdefcdb1893007ba3b91e25e678298047a70d1797a7
+  metadata.gz: 075799410c0f4b511ade42eded914a5d5287592297b77558f0ccd5f1b288893a31d9c160fb3a9952d34536228a656f7ab9c92f985e2e578bd8b945a6ba4e40b0
+  data.tar.gz: cd675321a91dfae484fc72447cca0378a74ab6b129b65c6d8e7c329d41cd688a70706d1624cc5b7951206c5417f17ba68f092c81c6b4435aa35f3a9ade545b19

data/.rubocop.yml

@@ -53,4 +53,8 @@ Metrics/ClassLength:
   Enabled: false
 
 Style/EachWithObject:
-  Enabled: false
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 15
+  Enabled: true

data/README.md

@@ -8,9 +8,7 @@
 * HTTP client to Zuora SOAP API
 * Authentication and session storage
 * SOAP XML request constructors from Ruby data
-* Support for custom Zuora fields
-* Light validation of SOAP call parameters
-* Light wrapper over response, providing a Ruby object interface over Zuora's returned XML response 
+* Light validation of top-level forms; field-level validation delegated to Zuora's responses.
 
 ## Usage
 
@@ -19,28 +17,11 @@
 
 Create a client
 ```ruby
-client = Zuora::Client.new(<username>, <password>) 
+client = Zuora::Client.new(<username>, <password>)
 ```
 
-Execute a SOAP request. All Zuora calls are supported: `.create()`, `.update()`, `.amend()`, `.generate()`, `.delete()`, `subscribe()`.
 
-### Quick Reference
-See examples below and integration specs for full interfaces. 
-```ruby
-client.call! :query, "SELECT Id FROM Account"
-client.call! :create, type: :Account, objects: [{}, {}]
-client.call! :update, type: :Invoice, objects: [{ id: '123' }, { id: '123' }]
-client.call! :delete, ids: ['123', '456']
-client.call! :amend, amendments: {}, amend_options: {}, :preview_options: {}
-client.call! :subscribe, 
-  account: {}
-  payment_method: {}
-  bill_to_contact: {}
-  sold_to_contact: {}
-  subscribe_options: {}
-  subscription: {}
-  rate_plan: {}
-```
+Execute a SOAP request. Currently only  `:create` and `:subscribe` are supported
 
 #### Create Example
 
@@ -51,8 +32,11 @@ response = client.call! :create,
     invoice_date: '2016-03-01',
     target_date: '2016-03-01'
   }]
+    
 ```
+
 This would generate SOAP XML, make, and return an authenticated SOAP request.
+
 ```xml
     <?xml version="1.0"?>
     <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.zuora.com/" xmlns:obj="http://object.api.zuora.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
@@ -72,10 +56,12 @@ This would generate SOAP XML, make, and return an authenticated SOAP request.
     </soapenv:Envelope>
 ```
 
-A response object is returned. You can access the raw response:
+A response object is returned, having status and body
+
 ```ruby
-response.raw.body
+response.body
 ```
+
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
@@ -90,15 +76,18 @@ response.raw.body
 </soapenv:Envelope>
 ```
 
-The `.to_h` method provides an interface that can be navigated as a hash or object.
+This XML body, in turn, could be parsed with Nokogiri for further work.
 
 ```ruby
-response.to_h.envelope.body.create_response.result 
-=> { id: '2c92c0f9526913e301526a7863df4647', success: true }
+response_xml = Nokogiri::XML(response.body)
+success = response_xml.xpath(
+ '/soapenv/Envelope/soapenv:Body/api:createResponse/api:result/api:Success'
+ ).text == 'true'
 ```
 
-#### .subscribe() example
-Subscribe is a very large call that involves a lot of data. See the integration spec `spec/zuora/integration/subscription_spec.rb` for full example
+
+#### Subscribe Example
+Subscribe is a very large call that involves a lot of data. See the integration spec `spec/zuora/integration/subscription_spec` for full example
 
  ```ruby
 response = client.call! :subscribe, 
@@ -126,14 +115,16 @@ response = client.call! :subscribe,
      - 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
-    - Redesign API, eliminate previous Model constructs
-    - Implement SOAP API Client, as it provides fuller functionality than REST 
+    - Implement SOAP API Client; it provides fuller functionality than REST 
     - Focus on constructing + composing hash-like Ruby objects into XML SOAP requests 
-    - Add support for custom fields
-    - Remove object-level validations; relies on Zuora's own error responses. Light validations on call constructors.
-    - Provide object/hash lookup capabilities on Zuora Responses
+    - 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.
+
 # 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

@@ -24,6 +24,7 @@ module Zuora
 end
 
 require_relative 'zuora/version'
+require_relative 'zuora/errors'
 require_relative 'zuora/utils/envelope'
 require_relative 'zuora/client'
 require_relative 'zuora/object'

data/lib/zuora/client.rb

@@ -3,12 +3,6 @@ require 'faraday_middleware'
 require 'nokogiri'
 
 module Zuora
-  # Unable to connect. Check username / password
-  SoapConnectionError = Class.new StandardError
-
-  # Non-success response
-  SoapErrorResponse = Class.new StandardError
-
   class Client
     attr_accessor :session_token
 
@@ -40,7 +34,7 @@ module Zuora
 
       handle_auth_response auth_response
     rescue Object => e
-      raise SoapConnectionError, e
+      raise Zuora::Errors::SoapConnectionError, e
     end
 
     # Fire a request
@@ -55,7 +49,11 @@ module Zuora
         request.body = body.to_xml
       end
 
-      Zuora::Response.new(raw_response)
+      response = Zuora::Response.new(raw_response)
+
+      response.handle_errors(response.to_h)
+
+      response
     end
 
     # The primary interface via which users should make SOAP requests.
@@ -73,8 +71,8 @@ module Zuora
     private
 
     # Generate envelope for request
-    # @param [Symbol] call name - one of the supported calls (see #call)
-    # @param [Callable] builder_modifier - function taking a builder
+    # @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
@@ -89,13 +87,13 @@ module Zuora
     # Handle auth response, setting session
     # @params [Faraday::Response]
     # @return [Faraday::Response]
-    # @throw [SoapErrorResponse]
+    # @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 SoapErrorResponse, message
+        fail Zuora::Errors::InvalidCredentials, message
       end
       response
     end
@@ -104,9 +102,7 @@ module Zuora
     # for use in subsequent requests
     # @param [Faraday::Response] response - response to auth request
     def extract_session_token(response)
-      Nokogiri::XML(response.raw.body).xpath(
-        SESSION_TOKEN_XPATH, Zuora::NAMESPACES
-      ).text
+      response.to_h.envelope.body.login_response.result.session
     end
 
     # Initializes a connection using api_url

data/lib/zuora/errors.rb

@@ -0,0 +1,18 @@
+module Zuora
+  module Errors
+    class InvalidValue < StandardError
+      attr_reader :response
+
+      def initialize(msg = nil, response = nil)
+        @response = response
+        super(msg)
+      end
+    end
+
+    class InvalidCredentials < StandardError
+    end
+
+    class SoapConnectionError < StandardError
+    end
+  end
+end

data/lib/zuora/response.rb

@@ -2,6 +2,7 @@ require 'active_support/core_ext/hash/conversions'
 
 module Zuora
   class Response
+    ERROR_STRINGS = ['Missing required value', 'are required fields'].freeze
     attr_reader :raw
 
     # @param [Faraday::Response]
@@ -18,8 +19,32 @@ module Zuora
       Hashie::Mash.new(symbolize_keys_deep(hash))
     end
 
+    # @param [Hash] hash
+    def handle_errors(hash)
+      errors = []
+
+      hash.each do |key, value|
+        if value.is_a?(Hash)
+          handle_errors(value)
+        elsif value.is_a?(Array)
+          value.each { |v| handle_errors(v) }
+        elsif error?(key, value)
+          errors << value
+        end
+      end
+
+      raise_errors(errors) if errors.present?
+    end
+
     private
 
+    # @param [String|Symbol] key
+    # @param [String] value
+    def error?(key, value)
+      ERROR_STRINGS.any? { |str| value.to_s.match(str) } ||
+        key.to_s.casecmp('message').zero?
+    end
+
     # Given a key, convert to symbol, removing XML namespace, if any.
     # @param [String] key - a key, either "abc" or "abc:def"
     # @return [Symbol]
@@ -46,5 +71,12 @@ module Zuora
         [symbolize_key(key), value]
       end]
     end
+
+    # @param [Array] errors
+    def raise_errors(errors)
+      error_string = errors.join(',')
+      error = Zuora::Errors::InvalidValue.new(error_string, to_h)
+      fail error
+    end
   end
 end

data/lib/zuora/utils/envelope.rb

@@ -65,7 +65,6 @@ module Zuora
       # @return [Symbol] - e.g. :SomeKeyName or :SomeKeyName__c
       def self.to_zuora_key(key)
         custom_field_matcher = Regexp.new CUSTOM_FIELD_STRING
-
         matches = custom_field_matcher.match(key.to_s)
         suffix = ''
 

data/lib/zuora/version.rb

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

data/zuora_ruby.gemspec

@@ -46,7 +46,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rspec'
   spec.add_development_dependency 'rspec-its'
   spec.add_development_dependency 'rspec_junit_formatter', '0.2.2'
-  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop', '0.36.0'
   spec.add_development_dependency 'webmock'
   spec.add_development_dependency 'vcr'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zuora-ruby
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Contactually Engineering
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-02 00:00:00.000000000 Z
+date: 2016-02-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -224,16 +224,16 @@ dependencies:
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.36.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.36.0
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -294,6 +294,7 @@ files:
 - lib/zuora/calls/upsert.rb
 - lib/zuora/client.rb
 - lib/zuora/dispatcher.rb
+- lib/zuora/errors.rb
 - lib/zuora/object.rb
 - lib/zuora/response.rb
 - lib/zuora/utils/envelope.rb
@@ -320,7 +321,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: A Ruby wrapper for Zuora API.