zuora-ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: da6c115de2be80e51003cee17072c6c06e578199
-  data.tar.gz: 6e48747729c511bd9fd2892eb8d97b1b9a3786a8
+  metadata.gz: 59ac3797046acdb3f30dbd498d3f5368024d6c8f
+  data.tar.gz: c747cfe5f6c0e2dfeeb46da7a0279761e201ecba
 SHA512:
-  metadata.gz: c1ea116b905657af8fef4d060239583187eefa02fbceb623ce1676a083efd3a2cb46916cec0c0beed5cedab0ca802abf3ccf42aab24b1bf3d2613744ae00e713
-  data.tar.gz: 7bdeb438f2581dfa8dc1aa9d01c008ba8cfdad614831bf0de642ef56a3e6ecf197b81a2919082d735dc5c7c62bfcefa3c6af858210e90062482587aabfc932fd
+  metadata.gz: a2e9865623c907ad008b942f39fb831979f6fe65f8b7d159f4176ae074ea41867e38883d77e891922e1e3e70da7685a3ad617dbe9cbf6aedfefceba8513f2b56
+  data.tar.gz: ded935331529eecc8ce365652be19e7fadb252c949e919d7e0bca07af74211d7f1cf5cc4264c3dd2d721bfdefcdb1893007ba3b91e25e678298047a70d1797a7

data/.gitignore

@@ -9,4 +9,5 @@
 /tmp/
 .env
 .byebug_history
-zuora-ruby*.gem
+zuora-ruby*.gem
+xml-debug/

data/.rubocop.yml

@@ -3,6 +3,7 @@ AllCops:
     - 'db/**/*'
     - 'config/**/*'
     - 'vendor/**/*'
+    - 'scratchpad.rb'
 
 Style/Encoding:
   Enabled: true
@@ -43,4 +44,13 @@ Style/MultilineOperationIndentation:
   EnforcedStyle: indented
   SupportedStyles:
     - aligned
-    - indented
+    - indented
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Style/EachWithObject:
+  Enabled: false

data/README.md

@@ -2,195 +2,115 @@
 [![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)
 
-# Zuora REST API: Ruby Client
+# Zuora SOAP API Client
 
-This library implements a Ruby client wrapping Zuora's REST API.
+## Features
+* 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 
 
-### Model
-A base module called `DirtyValidAttr` provides `dirty_model_attr`
-* **Accessors**: attribute name provides getters and setters, as in `attr_accessor`
-* **Validations** `valid: max_length(3) ` 
-    *  Includes a library of predicate higher order validation functions
-* **Coercions** `coerce: ->(value) { value.to_s } `
-* **Type Checks** `type: String`
-* **Required Attributes**: `:required: true`
+## Usage
 
-### Resource 
-* **HTTP requests**: that are authenticated with provided credentials
-* **Zuora API endpoints**: 
 
-### Utilities
-- **Serialization**: Ruby <=> JSON serializer provided, just provide a module or class that respnds to `.serialize(hash)` 
+### Client
 
-### Development: Specs and Testing
-- **Factories**: for generating sample valid and invalid data that works with the API
-- **Unit**: factories for testing model valdiations 
-- **Integration**: Tests against or memoized (via `VCR`) HTTP responses
-
-## Quickstart
+Create a client
 ```ruby
-# Connect
-client = Zuora::Client.new(username, password) 
-# Create a model
-account = Zuora::Models::Account.new(...)
-serializer = Zuora::Serializers::Attribute
-# Low level HTTP API
-client.get('/rest/v1/accounts', serializer.serialze account)
-# High Level Resource API 
-Zuora::Resources::Account.create! client, account, serializer
+client = Zuora::Client.new(<username>, <password>) 
 ```
-## Key Features & Concepts 
-1. ***Client:*** Create a client by providing username and password.
-This authenticates and stores the returned session cookie 
-used in subsequent requests. An optional third, truthy value enables Sandbox instead of production mode.
 
-2. ***HTTP:***
-Use `client.<get|post|put>(url, params)` to make HTTP requests via the authenticated client. Request and response body will be converted to/from Ruby via `farraday_middleware`. 
+Execute a SOAP request. All Zuora calls are supported: `.create()`, `.update()`, `.amend()`, `.generate()`, `.delete()`, `subscribe()`.
 
-3. ***Models:***  Ruby interface for constructing valid Zuora objects.
-  - Documentation coming soon. In the mean time, check comments in `Zuora::Models::Dirty`.
+### 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: {}
+```
 
-4. **Serializers:** Recursive data transformations for mapping between formats; a Ruby -> JSON serializer is included; `snake_case` attributes are transformed into JSON `lowerCamelCase` recursively in a nested structure.
-  - ex. `Zuora::Serializers::Attribute.serialize account` 
+#### Create Example
 
-5. **Resources:** Wraps Zuora REST API endpoints. Hand a valid model and (optionally) a serializer to a Resource to trigger a request. Request will be made for valid models only. An exception will be raised if the model is invalid. Otherwise, a `Farraday::Response` object will be returned (responding to `.status`, `.headers`, and `.body`).
+ ```ruby
+response = client.call! :create,
+  type: :BillRun,
+  objects: [{ 
+    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">
+      <soapenv:Header>
+        <api:SessionHeader>
+          <api:session><!-- SESSION TOKEN HERE --></api:session>
+        </api:SessionHeader>
+      </soapenv:Header>
+      <soapenv:Body>
+        <api:create>
+          <api:zObjects xsi:type="obj:BillRun">
+            <obj:InvoiceDate>2016-03-01</obj:InvoiceDate>
+            <obj:TargetDate>2016-03-01</obj:TargetDate>
+          </api:zObjects>
+        </api:create>
+      </soapenv:Body>
+    </soapenv:Envelope>
+```
 
-6. **Factories:** Factories are set up for easily constructing Zuora requests in development (via `factory_girl`) 
+A response object is returned. You can access the raw response:
 ```ruby
-account = create :account, :credit_card => create(:credit_card),
-                           :sold_to_contact => create(:contact),
-                           :bill_to_contact => create(:contact)
-                           
-account.valid? # => true
+response.raw.body
+```
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+  <soapenv:Body>
+    <api:createResponse xmlns:api="http://api.zuora.com/">
+      <api:result>
+        <api:Id>2c92c0f9526913e301526a7863df4647</api:Id>
+        <api:Success>true</api:Success>
+      </api:result>
+    </api:createResponse>
+  </soapenv:Body>
+</soapenv:Envelope>
 ```
-7. **Test coverage:** Unit and integration specs coverage via `rspec`. Coming soon: HTTP response caching (using `VCR`)
-
-## Models
-Models implement (recursive, nested) Zuora validations using `ActiveModel::Model` and soon, dirty attribute tracking via `ActiveModel::Dirty`
-* Account
-* CardHolder
-* Contact
-* PaymentMethod::CreditCard
-* RatePlan
-* RatePlanCharge
-* Subscription
-* Tier
-
-## Resources 
-In module  `Zuora::Resources::` 
-* `Account.create!` **[working]**
-* `Account.update!` **[working]**
-* `Subscription.create!` **[working]**
-* `Subscription.update!` **[working]**
-* `Subscription.cancel!` [in progress]
-* `PaymentMethod.update!` [in progress]
-
-## Examples
-### Creating an Account
+
+The `.to_h` method provides an interface that can be navigated as a hash or object.
 
 ```ruby
-username = 'your@username.com'
-password = 'super_secure_password'
-
-client = Zuora::Client.new(username, password, true) # true for sandbox
-
-account = Zuora::Models::Account.new(
-  :name => 'Abc',
-  :auto_pay => true,
-  :currency => 'USD',
-  :bill_cycle_day => '0',
-  :payment_term => 'Net 30',
-  :bill_to_contact => Zuora::Models::Contact.new(
-    :first_name => 'Abc',
-    :last_name => 'Def',
-    :address_1 => '123 Main St',
-    :city => 'Palm Springs',
-    :state => 'FL',
-    :zip_code => '90210',
-    :country => 'US'
-  ),
-  :sold_to_contact => Zuora::Models::Contact.new(
-    :first_name => 'Abc',
-    :last_name => 'Def',
-    :country => 'US'
-  ),
-  :credit_card => Zuora::Models::PaymentMethod.new(
-    :card_type => 'Visa',
-    :card_number => '4111111111111111',
-    :expiration_month => '03',
-    :expiration_year => '2017',
-    :security_code => '122',
-  )
-)
-
-# Create an account in one of two ways:
-
-serializer = Zuora::Serializers::Attribute
-
-# Using the low-level API exposed by `Client`
-response = client.post('/rest/v1/accounts', serializer.serialize accont)
-
-# or using the higher-level resource API
-response = Zuora::Resources::Accounts.create!(client, account, serializer)
-
-# Le response
-
-pp response
-
-#<Faraday::Response:0x007f8033b05f08
- @env=
-  #<struct Faraday::Env
-   method=:post,
-   body=
-    {"success"=>true,
-     "accountId"=>"2c92c0fa521b466c0152250822741a71",
-     "accountNumber"=>"A00000038",
-     "paymentMethodId"=>"2c92c0fa521b466c0152250829c81a7b"},
-   url=#<URI::HTTPS https://apisandbox-api.zuora.com/rest/v1/accounts>,
-   request=
-    #<struct Faraday::RequestOptions
-     params_encoder=nil,
-     proxy=nil,
-     bind=nil,
-     timeout=nil,
-     open_timeout=nil,
-     boundary=nil,
-     oauth=nil>,
-   request_headers=
-    {"User-Agent"=>"Faraday v0.9.2",
-     "Content-Type"=>"application/json",
-     "Cookie"=>
-      "ZSession=LBToVw72ZCAQLjdZ9Ksj8rx2BlP3NbgmMYwCzuf_slSJqIhMbJjdQ1T-4otbdfjUOImQ_XJOCbJgdCd7jHmGsnnJyG49NyRkI7FVKOukVQtdJssJ5n1xAXJeVjxj3qj97iiIZp697v3G2w86iCTN6kWycUlSVezBElbC8_EhScbx8YmaP4QJxXRIFHHdOQPq3IN-9ezk21Cpq3fdXn6s0fIPMU7NUFj7-kD4dcYNBAyd7i2fJVAIV31mXNBH2MuU;"},
-   ssl=
-    #<struct Faraday::SSLOptions
-     verify=false,
-     ca_file=nil,
-     ca_path=nil,
-     verify_mode=nil,
-     cert_store=nil,
-     client_cert=nil,
-     client_key=nil,
-     certificate=nil,
-     private_key=nil,
-     verify_depth=nil,
-     version=nil>,
-   parallel_manager=nil,
-   params=nil,
-   response=#<Faraday::Response:0x007f8033b05f08 ...>,
-   response_headers=
-    {"server"=>"Zuora App",
-     "content-type"=>"application/json;charset=utf-8",
-     "expires"=>"Sat, 09 Jan 2016 06:17:18 GMT",
-     "cache-control"=>"max-age=0, no-cache, no-store",
-     "pragma"=>"no-cache",
-     "date"=>"Sat, 09 Jan 2016 06:17:18 GMT",
-     "content-length"=>"165",
-     "connection"=>"close",
-     "set-cookie"=>
-      "ZSession=dOz9WgdPQbb9J9wzwhuR_t1j9feD4dYBUEZ_sjK6pS9KAaJtPdKN-jAivNELsaANWMJrvHW_1eLxT7XqzjLVBJKzLDJT7_0ucvzcrwNcwMW8mUGpeUhQQu_h2HzNH1kZjc1HX6pfw-BH66BafLemLIdqL75ifmglk8YuTOf_wTg54GsovkrgJCAp9zferw6pYHkZoQUXyH7zmUmmWvMAZ1ZVamhLOf1P3FrrHaw6eIiUj0ehlKvrtxB-GHIgYxh6; Path=/; Secure; HttpOnly"},
-   status=200>,
- @on_complete_callbacks=[]>
+response.to_h.envelope.body.create_response.result 
+=> { id: '2c92c0f9526913e301526a7863df4647', success: 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
+
+ ```ruby
+response = client.call! :subscribe, 
+  account: {...},
+  payment_method: {...},
+  bill_to_contact: {...},
+  sold_to_contact: {...},
+  subscription: {...},
+  rate_plan: {...}
+
 ```
+
 # Changelog
 * **[0.1.0 - 2016-01-12]** Initial release 
 * **[0.2.0] - 2016-01-14]** Models
@@ -205,6 +125,15 @@ pp response
      - 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
+    - Redesign API, eliminate previous Model constructs
+    - Implement SOAP API Client, as 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
+    - See integration specs for full interface
+    
 # Commit rights
 Anyone who has a patch accepted may request commit rights. Please do so inside the pull request post-merge.
 

data/bin/console

@@ -12,10 +12,10 @@ require 'zuora'
 # Pry.start
 
 require 'factory_girl'
-FactoryGirl.definition_file_paths = ['spec/zuora/factories']
+FactoryGirl.definition_file_paths = ['spec/factories']
 FactoryGirl.find_definitions
 # Short hand factory girl syntax
-include FactoryGirl::Syntax::Methods
+# include FactoryGirl::Syntax::Methods
 
 require 'irb'
 IRB.start

data/lib/utils/schema_model.rb

@@ -0,0 +1,194 @@
+require 'byebug'
+
+module SchemaModel
+  def self.included(base)
+    base.include InstanceMethods
+    base.extend ClassMethods
+  end
+
+  module ClassMethods
+    # Dynamically configures accessors, dirty tracking, validation,
+    # and serialization methods given definition in opts
+    # @param [Object] _name - name of schema
+    # @param [Hash] opts - See below
+    #
+    #  class AwesomeClass
+    #    schema :my_schema,
+    #      id: {
+    #       type: Numeric,             # value will be checked using is_a?
+    #       valid: -> (v) { v > 0 },   # value will be validated by calling this
+    #       schema: [ChildClass]       # single or collection recursive checks
+    #       doc: 'Id, number greater than 1'  # documentation string
+    #      }
+    #  end
+    #
+    #  a = AwesomeClass.new(id: 1)
+    #  a.valid? => true
+    #  a.errors => {}
+    #
+    def schema(_name, opts = {})
+      define_method(:definition) { opts }
+
+      opts.each do |k, definition|
+        # Reader
+        attr_reader k
+
+        # Writer
+        define_writer! k, definition
+      end
+    end
+
+    private
+
+    # Helper for dynamically defining writer method
+    # @param [Symbol] k - name of attribute
+    # @param [Hash] definition - See docstring for schema above
+    def define_writer!(k, definition)
+      define_method("#{k}=") do |value|
+        # Recursively convert hash and array of hash to schematized objects
+        value = ensure_schema value, definition[:schema]
+
+        # Initial value
+        instance_variable_set "@#{k}", value
+
+        # Dirty tracking
+        self.changed_attributes ||= Set.new
+        self.changed_attributes << k
+      end
+    end
+  end
+
+  module InstanceMethods
+    attr_accessor :changed_attributes
+
+    def initialize(attrs = {})
+      attrs.each do |attr, v|
+        send("#{attr}=", v)
+      end
+    end
+
+    def errors
+      check definition, self
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    def to_json
+      return nil unless changed_attributes
+      Hash[
+        changed_attributes.map { |attr| serialize_attr(attr) }
+      ]
+    end
+
+    private
+
+    # @param [Symbol] attr
+    # @return [Array]
+    def serialize_attr(attr)
+      value = send(attr)
+      value = if value.is_a?(Hash) || value.is_a?(SchemaModel)
+                value.to_json
+              elsif value.is_a?(Array)
+                value.map(&:to_json)
+              else
+                value
+              end
+
+      [attr.to_s.camelize(:lower), value]
+    end
+
+    # Given a schema and a value which may be a single record or collection,
+    # collect and return any errors.
+    # @param [SchemaModel] child_schema - A schema object class
+    # @param [Object] value - Array of models or single model
+    # @return [Object] Array of errors hashes, or one hash.
+    #                   Structure matches 'value' input
+    def check_children(child_schema, value)
+      return unless child_schema && value.present?
+
+      if value.is_a? Array
+        value.map(&:errors).reject(&:empty?)
+      else
+        value.errors
+      end
+    end
+
+    # Checks that value is of correct type
+    # @param [Maybe Class] type - type to check using value.is_a?(type)
+    # @param [Object] value - value to check
+    # @return [Maybe String] error message
+    def check_type(type, value)
+      return unless type && value && !value.is_a?(type)
+
+      "should be of type #{type} but is of type #{value.class}"
+    end
+
+    # Checks that required field meets validation
+    # @param [Boolean or Callable] valid - callable validation fn or boolean
+    #                               function will be called with value
+    # @param [Object] value - value to check
+    # @return [Maybe String] error message
+    def check_validation(valid, value)
+      return unless valid && value
+
+      passes_validation = begin
+                            valid.call(value)
+                          rescue
+                            false
+                          end
+      passes_validation ? nil : 'is invalid'
+    end
+
+    # Mutates errors, adding in error messages scoped to the attribute and key
+    # @param [Maybe Hash] errors -
+    # @param [Symbol] attr - name of attribute under check
+    # @param [Symbol] key - name of validation step
+    # @param [Object] val - data to append
+    def append!(errors, attr, key, val)
+      return unless val.present?
+
+      errors ||= {}
+      errors[attr] ||= {}
+      errors[attr][key] = val
+    end
+
+    # @param [Hash] schema
+    # @param [Hash|Object] data
+    # @return [Hash]
+    def check(schema, data)
+      schema.reduce({}) do |errors, (attr, defn)|
+        # Destructuring
+        child_schema, type = defn.values_at :schema, :type
+
+        # Get the value for this attribute
+        value = data.send attr
+
+        # Add error messages
+        append! errors, attr, :child, check_children(child_schema, value)
+        append! errors, attr, :type, check_type(type, value)
+        errors
+      end
+    end
+
+    # Constructs new instance(s) of provided Schema model from hash or
+    # array of hash values. Allows for modeling of has_one and has_many.
+    # @param [Array of Hashes or SchemaModels] value
+    # @param [SchemaModel] child_schema
+
+    def ensure_schema(value, child_schema)
+      if value.present? && child_schema.present?
+        value = if child_schema.is_a?(Array)
+                  value.map do |item|
+                    item.is_a?(SchemaModel) ? item : child_schema[0].new(item)
+                  end
+                else
+                  value.is_a?(SchemaModel) ? value : child_schema.new(value)
+                end
+      end
+
+      value
+    end
+  end
+end