zuora-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5415a26e1054e37bd49d820c0a79ce67afee2b23
-  data.tar.gz: be862d326b31f2f0133fd7b19084034ca30b55bf
+  metadata.gz: da6c115de2be80e51003cee17072c6c06e578199
+  data.tar.gz: 6e48747729c511bd9fd2892eb8d97b1b9a3786a8
 SHA512:
-  metadata.gz: 818e018dfaac566ef45e4824cc2de1c7c7910be67e89486a068b185f26a95b9b9c182c8d443b6dcb03fa5a7b6789dc487c6ccb45cef2d874fb70afd6935dbe3f
-  data.tar.gz: 24bed325e1caab98bda4d1fa7f9492346215392c2a5710106775102a0679673b55f484802126efba89de796117fdb2d889ae031083736bd3e4ae979c12e716af
+  metadata.gz: c1ea116b905657af8fef4d060239583187eefa02fbceb623ce1676a083efd3a2cb46916cec0c0beed5cedab0ca802abf3ccf42aab24b1bf3d2613744ae00e713
+  data.tar.gz: 7bdeb438f2581dfa8dc1aa9d01c008ba8cfdad614831bf0de642ef56a3e6ecf197b81a2919082d735dc5c7c62bfcefa3c6af858210e90062482587aabfc932fd

data/.gitignore

@@ -8,4 +8,5 @@
 /spec/reports/
 /tmp/
 .env
-.byebug_history
+.byebug_history
+zuora-ruby*.gem

data/.rubocop.yml

@@ -17,6 +17,30 @@ Style/Encoding:
 AbcSize:
   Enabled: false
 
-MethodLength:
-  Enabled: true
-  Max: 25
+Rails/TimeZone:
+  Enabled: false
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+  SupportedStyles:
+    - with_first_parameter
+    - with_fixed_indentation
+
+Style/CaseIndentation:
+  IndentWhenRelativeTo: end
+  SupportedStyles:
+    - case
+    - end
+  IndentOneStep: false
+
+Style/IndentHash:
+  EnforcedStyle: consistent
+  SupportedStyles:
+    - special_inside_parentheses
+    - consistent
+
+Style/MultilineOperationIndentation:
+  EnforcedStyle: indented
+  SupportedStyles:
+    - aligned
+    - indented

data/README.md

@@ -5,9 +5,27 @@
 # Zuora REST API: Ruby Client
 
 This library implements a Ruby client wrapping Zuora's REST API.
-- **Validations** (via `activemodel`)
-- **HTTP** (via `faraday`)
-- **Serialization**: To/from Ruby / JSON
+
+### 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`
+
+### 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)` 
+
+### 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
 ```ruby
@@ -15,9 +33,6 @@ This library implements a Ruby client wrapping Zuora's REST API.
 client = Zuora::Client.new(username, password) 
 # Create a model
 account = Zuora::Models::Account.new(...)
-# Validate
-account.valid? # true or false, check account.errors if false
-# Select a serializer (snake_case -> lowerCamelCase)
 serializer = Zuora::Serializers::Attribute
 # Low level HTTP API
 client.get('/rest/v1/accounts', serializer.serialze account)
@@ -33,14 +48,10 @@ used in subsequent requests. An optional third, truthy value enables Sandbox ins
 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`. 
 
 3. ***Models:***  Ruby interface for constructing valid Zuora objects.
-  - `account = Zuora::Models::Account.new(:attribute => 'name')`
-  - `account.valid?`  a boolean indicating validity
-  - `account.errors`  a hash of error message(s)
-  - `account.attributes` an array of attribute names
+  - Documentation coming soon. In the mean time, check comments in `Zuora::Models::Dirty`.
 
 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` 
-  
 
 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`).
 
@@ -68,9 +79,9 @@ Models implement (recursive, nested) Zuora validations using `ActiveModel::Model
 ## Resources 
 In module  `Zuora::Resources::` 
 * `Account.create!` **[working]**
-* `Account.update!` [in progress]
-* `Subscription.create!` [in progress]
-* `Subscription.update!` [in progress]
+* `Account.update!` **[working]**
+* `Subscription.create!` **[working]**
+* `Subscription.update!` **[working]**
 * `Subscription.cancel!` [in progress]
 * `PaymentMethod.update!` [in progress]
 
@@ -181,11 +192,18 @@ pp response
  @on_complete_callbacks=[]>
 ```
 # Changelog
-* **[0.1.0] Initial release** 
-# Roadmap
-* **[0.1.1] Additional resources** See Resource list above
-* **[0.2.0] Add VCR** Fast, deterministic HTTP requests and responses
-* **[0.3.0] Dirty attribute tracking:** only serialize attributes that have been explicitly set. Currently, unset attributes are sent as `nil` which might override Zuora defaults.
+* **[0.1.0 - 2016-01-12]** Initial release 
+* **[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. 
+       * required attributes, coercions, validations, type checking
+       * dirty attribute tracking
+       * extensible predicate library
+     - Implements fine-grained validations per Zuora spec
+     - Removes invalid model state paradigm used via `ActiveModel` in version 0.1.0.
+     -  A model now performs its validations on `.new`, and will raise a detailed exception on mistyped, invalid or uncoercable data.
+     - Adds VCR for mocking out HTTP requests
+     - Adds integration specs for `Subscribe` `create!` and `update!` and `Account` `create!` and `update!`
 
 # 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

@@ -23,7 +23,58 @@ module Zuora
 
   PAYMENT_TERMS = ['Due Upon Receipt', 'Net 30', 'Net 60', 'Net 90']
 
+  # SUBSCRIPTION
+
   SUBSCRIPTION_TERM_TYPES = %w(TERMED EVERGREEN)
+
+  DISCOUNT_TYPES = %w(ONETIME
+                      RECURRING
+                      USAGE
+                      ONETIMERECURRING
+                      ONETIMEUSAGE
+                      RECURRINGUSAGE
+                      ONETIMERECURRINGUSAG) # typo in zuora docs?
+
+  DISCOUNT_LEVELS = %w(rateplan subscription account)
+
+  LIST_PRICE_BASES = %w(Per_Billing_Period
+                        Per_Month
+                        Per_Week)
+
+  TRIGGER_EVENTS = %w(UCE USA UCA USD)
+
+  END_DATE_CONDITIONS = %w(Subscription_End
+                           Fixed_Period
+                           Specific_End_Date)
+
+  UP_TO_PERIODS = %w(Days Weeks Months Years)
+
+  BILLING_PERIODS = %w(Month
+                       Quarter
+                       Semi_Annual
+                       Annual
+                       Eighteen_Months
+                       Two_Years
+                       Three_Years
+                       Five_Years
+                       Specific_Months
+                       Subscription_Term
+                       Week
+                       Specific_Weeks)
+
+  BILLING_TIMINGS = %w(IN_ADVANCE IN_ARREARS)
+
+  BILL_CYCLE_TYPES = %w(DefaultFromCustomer
+                        SpecificDayofMonth
+                        SubscriptionStartDay
+                        ChargeTriggerDay
+                        SpecificDayOfWeek)
+
+  PRICE_CHANGE_OPTIONS = %w(NoChange
+                            SpecificPercentageValue
+                            UseLatestProductCatalogPricing)
+
+  WEEKDAYS = %w(Sunday Monday Tuesday Wednesday Thursday Friday Saturday)
 end
 
 require_relative 'zuora/version'

data/lib/zuora/client.rb

@@ -11,7 +11,7 @@ module Zuora
   ErrorResponse = Class.new StandardError
 
   class Client
-    attr_accessor :connection
+    attr_reader :connection
 
     # Creates a connection instance.
     # Makes an initial HTTP request to fetch session token.
@@ -22,30 +22,19 @@ module Zuora
     # @param [Boolean] sandbox
     # @return [Zuora::Client] with .connection, .put, .post
     def initialize(username, password, sandbox = false)
-      url = api_url sandbox
+      base_url = api_url sandbox
+      conn = connection base_url
 
-      response = connection(url).post do |req|
-        req.url '/rest/v1/connections'
-        req.headers['apiAccessKeyId'] = username
-        req.headers['apiSecretAccessKey'] = password
-        req.headers['Content-Type'] = 'application/json'
-      end
+      response = auth_request conn, username, password
 
-      if response.status == 200
-        @auth_cookie = response.headers['set-cookie'].split(' ')[0]
-        @connection = connection(url)
-      else
-        fail ConnectionError, response.body['reasons']
-      end
+      handle_response response, conn
     end
 
     # @param [String] url - URL of request
     # @return [Faraday::Response] A response, with .headers, .status & .body
     def get(url)
       @connection.get do |req|
-        req.url url
-        req.headers['Content-Type'] = 'application/json'
-        req.headers['Cookie'] = @auth_cookie
+        set_request_headers! req, url
       end
     end
 
@@ -54,9 +43,7 @@ module Zuora
     # @return [Faraday::Response] A response, with .headers, .status & .body
     def post(url, params)
       response = @connection.post do |req|
-        req.url url
-        req.headers['Content-Type'] = 'application/json'
-        req.headers['Cookie'] = @auth_cookie
+        set_request_headers! req, url
         req.body = JSON.generate params
       end
 
@@ -72,11 +59,9 @@ module Zuora
     # @param [Params] params - Data to be sent in request body
     # @return [Faraday::Response] A response, with .headers, .status & .body
     def put(url, params)
-      response = @connection.put do |req|
-        req.url url
-        req.headers['Content-Type'] = 'application/json'
-        req.headers['Cookie'] = @auth_cookie
-        req.body = JSON.generate params
+      response = @connection.put do |request|
+        set_request_headers! request, url
+        request.body = JSON.generate params
       end
 
       response
@@ -89,6 +74,47 @@ module Zuora
 
     private
 
+    # Make connection attempt
+    # @param [Faraday::Connection] conn
+    # @param [String] username
+    # @param [String] password
+    def auth_request(conn, username, password)
+      conn.post do |request|
+        set_auth_request_headers! request, username, password
+      end
+    end
+
+    # Sets instance variables or throws Connection error
+    # @param [Faraday::Response] response
+    # @param [Faraday::Connection] conn
+    def handle_response(response, conn)
+      if response.status == 200
+        @auth_cookie = response.headers['set-cookie'].split(' ')[0]
+        @connection = conn
+      else
+        fail ConnectionError, response.body['reasons']
+      end
+    end
+
+    # @param [Faraday::Request] request - Faraday::Request builder
+    # @param [String] username - Zuora username
+    # @param [String] password - Zuora password
+    def set_auth_request_headers!(request, username, password)
+      request.url '/rest/v1/connections'
+      request.headers['apiAccessKeyId'] = username
+      request.headers['apiSecretAccessKey'] = password
+      request.headers['Content-Type'] = 'application/json'
+    end
+
+    # @param [Faraday::Request] request - Faraday Request builder
+    # @param [String] url - Relative URL for HTTP request
+    # @return [Nil]
+    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)

data/lib/zuora/models.rb

@@ -1,9 +1,10 @@
-require_relative 'models/utils'
+require_relative 'models/dirty'
+require_relative 'models/validation_predicates'
 
-require_relative 'models/account'
-require_relative 'models/card_holder'
 require_relative 'models/contact'
 require_relative 'models/payment_method'
+require_relative 'models/account'
+require_relative 'models/card_holder'
 require_relative 'models/rate_plan'
 require_relative 'models/rate_plan_charge'
 require_relative 'models/subscription'

data/lib/zuora/models/account.rb

@@ -1,53 +1,64 @@
-# encoding: utf-8
-
 module Zuora
   module Models
     class Account
-      include ActiveModel::Model
-      # See http://api.rubyonrails.org/classes/ActiveModel/Dirty.html
-
-      ATTRIBUTES = :account_number,
-                   :auto_pay,
-                   :bill_to_contact,
-                   :bill_cycle_day,
-                   :crm_id,
-                   :currency,
-                   :credit_card,
-                   :name,
-                   :hpm_credit_card_payment_method_id,
-                   :notes,
-                   :invoice_template_id,
-                   :communication_profile_id,
-                   :payment_gateway,
-                   :payment_term,
-                   :sold_to_contact,
-                   :subscription
-
-      attr_accessor(*ATTRIBUTES)
-
-      def attributes
-        ATTRIBUTES
-      end
-
-      Zuora::Models::Utils.validate_children self,
-                                             'contact',
-                                             :bill_to_contact,
-                                             :sold_to_contact
-
-      validates :auto_pay,
-                :bill_to_contact,
-                :credit_card,
-                :currency,
-                :name,
-                :payment_term,
-                :sold_to_contact,
-                presence: true
-
-      validates :currency,
-                length: { is: 3 }
-
-      validates :payment_term,
-                inclusion: { in: Zuora::PAYMENT_TERMS }
+      include DirtyValidAttr
+
+      dirty_valid_attr :account_number,
+        type: String
+
+      dirty_valid_attr :auto_pay,
+        type: Boolean,
+        required?: true
+
+      dirty_valid_attr :bill_to_contact,
+        type: Zuora::Models::Contact,
+        required?: true
+
+      dirty_valid_attr :bill_cycle_day,
+        type: String
+
+      dirty_valid_attr :crm_id,
+        type: String
+
+      dirty_valid_attr :currency,
+        type: String,
+        valid?: length(3)
+
+      dirty_valid_attr :credit_card,
+        type: Zuora::Models::PaymentMethods::CreditCard,
+        required?: true
+
+      dirty_valid_attr :name,
+        type: String
+
+      dirty_valid_attr :hpm_credit_card_payment_method_id,
+        type: String
+
+      dirty_valid_attr :notes,
+        type: String
+
+      dirty_valid_attr :invoice_template_id,
+        type: String
+
+      dirty_valid_attr :communication_profile_id,
+        type: String
+
+      dirty_valid_attr :payment_gateway,
+        type: String
+
+      dirty_valid_attr :payment_term,
+        type: String,
+        required?: true,
+        valid?: one_of(Zuora::PAYMENT_TERMS)
+
+      dirty_valid_attr :sold_to_contact,
+        type: Zuora::Models::Contact,
+        required?: true
+
+      dirty_valid_attr :subscription,
+        type: String
+
+      alias_method :initialize, :initialize_attributes!
     end
   end
 end