root_insurance 1.7.4 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75e3ae3ca5078705c6a87fa245c3acefad9dcfca
-  data.tar.gz: 8f4d396c8d8d09d664807f94c1c96b0dd838c114
+  metadata.gz: 38199c8ed87d9e97b257db82410699f7ad6e4d1e
+  data.tar.gz: c9dc7652916e3f573f88362cb1444043c84eb043
 SHA512:
-  metadata.gz: ec930d343623b1626cb5bbadce8149aa25e33a50c24d9b73e3fe771b48d95dd5b747a1aa5cbd494868e0e3e5d5f86ed9b8b0d94bad3c363ba44953ae6eaa9a5d
-  data.tar.gz: aa96a45de85da0eaf866d8c9088c501fd30f3b35a380280a2057e2bfb23d2b7fd94dddd938fbf4d6e7504fd57e78b102d0ee6c93f29de43db761d1f7a4d10552
+  metadata.gz: 19350f52a045b3ebf508c34c11f74d9e68ee25241a4e672930a290c377f50b5a7ce0190a5c0e25b06b9f61cf68fc26a88df8e9793663332e09eedd112c48becc
+  data.tar.gz: 5b55dffc3ea93c055f3e0bf86e44ed6bb5179d34df4bd96a2474bc9e317ace06c4f5d0f5ccc58132e03532df96855bccd05f13555b12c11df7df68286de72d5f

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+# 1.8.0 - Release date: 2018-17-05
+* Removed old replace_policy method
+* Add support to filter on id number when listing policy holders
+* Added support to include oblects when getting a list of policy holders and a individual policy holder
+* Added more documentation
+
+
 # 1.7.4 - Release date: 2018-16-05
 * Added claim and call documentation
 

data/README.md

@@ -22,11 +22,18 @@ gem 'root_insurance'
 
 And then execute:
 
-    $ bundle
+```bash
+bundle
+```
 
-## Usage
+## Quick start
+1. Create an instance of `RootInsurance::Client`
+```ruby
+client = RootInsurance::Client.new("test_key_tYILz1640w9q5n5kNQUZ", '', :sandbox)
+```
 
-See the [wiki](https://github.com/root-community/root-insurance-ruby/wiki).
+2. Use the api
+See the documentation [here](https://www.rubydoc.info/gems/root_insurance/).
 
 ## Contributing
 If you wish to contribute to this repository, please fork it and send a PR our way.

data/lib/root_insurance/api/payment.rb

@@ -1,5 +1,32 @@
 module RootInsurance::Api
   module Payment
+
+    # Create a payment method
+    #
+    # @param [String] policy_holder_id The unique identifier of the policy holder.
+    # @param [String] type The payment method type. Curently only +'debit_order'+ is supported. If omitted, defaults to +'debit_order'+ (optional)
+    # @param [Hash] bank_details Bank details to use for the debit order. See below for details.
+    # @param [String] policy_ids The date on the which the incident occured. (optional)
+    # @return [Hash]
+    #
+    ## == Bank details
+    # [account_holder (string)]   Name of account holder.
+    # [bank (string)]   Bank name - one of [+absa+, +capitec+, +fnb+, +investec+, +nedbank+, +postbank+, +standard_bank+]
+    # [branch_code (string)]   Branch code for bank account
+    # [account_number (string)]   Bank account number
+    #
+    # @example
+    #  bank_details = {
+    #    first_name:     "Erlich",
+    #    last_name:      "Bachman",
+    #    bank:           "absa",
+    #    branch_code:    "12345",
+    #    account_number: "123456789"
+    #  }
+    #  client.create_payment_method(
+    #          policy_holder_id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e",
+    #          bank_details:     bank_details)
+    #
     def create_payment_method(policy_holder_id:, type: 'debit_order', bank_details: {}, policy_ids: nil)
       validate_bank_details(bank_details)
 
@@ -17,6 +44,16 @@ module RootInsurance::Api
       post("policyholders/#{policy_holder_id}/payment-methods", data)
     end
 
+    # Link a payment method to a policy
+    #
+    # @param [String] policy_id The unique identifier of the policy.
+    # @param [String] payment_method_id The unique identifier of the payment method.
+    #
+    # @example
+    #   client.link_payment_method(
+    #     policy_id:         "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e",
+    #     payment_method_id: "e0b7b222-772f-47ac-b08d-c7ba38aa1b25")
+    #
     def link_payment_method(policy_id:, payment_method_id:)
       data = {payment_method_id: payment_method_id}
 

data/lib/root_insurance/api/policy.rb

@@ -1,5 +1,17 @@
 module RootInsurance::Api
   module Policy
+
+    # Issue a policy
+    #
+    # @param [String] application_id The unique identifier of the application.
+    # @param [Hash, nil] app_data An object containing additional custom data for the policy.
+    # @return [Hash]
+    #
+    # @example
+    #   client.issue_policy(
+    #     application_id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e",
+    #     app_data:       {gadget_colour: "Space Grey"})
+    #
     def issue_policy(application_id:, app_data: nil)
       data = {
         application_id: application_id,
@@ -10,57 +22,140 @@ module RootInsurance::Api
       post(:policies, data)
     end
 
-    def add_policy_beneficiary(policy_id:, id:, first_name:, last_name:, percentage:)
+    # Add a benificiary to a policy
+    #
+    # @param [String] policy_id The unique identifier of the policy.
+    # @param [String] first_name The beneficiary's first name
+    # @param [String] last_name The beneficiary's last name
+    # @param [Hash] id An hash containing the beneficiary's identification number, type and country. See below.
+    # @param [Integer] percentage An integer representing the percentage of a claim payout that the beneficiary should receive.
+    # @param [String] cellphone Hash containing beneficiary's cellphone number and country. See below for details. (optional)
+    # @return [Hash]
+    #
+    ## == ID
+    # [type (string or symbol)]   Either +:id+ or +:passport+
+    # [number (string)]   The id or passport number
+    # [country (string)]   The ISO Alpha-2 country code of the country of the id/passport number.
+    #
+    ## == Cellphone
+    # [number (string)]   The cellphone number
+    # [country (string)]   The ISO Alpha-2 country code of the country of the cellphone number.
+    #
+    # @example
+    #   client.add_policy_beneficiary(
+    #     policy_id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e",
+    #     first_name: "Jared"
+    #     last_name:  "Dunn",
+    #     id:         {type: :id, number: "8704094800082", country: "ZA"},
+    #     percentage: 100)
+    #
+    def add_policy_beneficiary(policy_id:, id:, first_name:, last_name:, percentage:, cellphone: nil)
       raise ArgumentError.new('id needs to be a hash') unless id.is_a? Hash
 
       data = {
         id:         id,
         first_name: first_name,
         last_name:  last_name,
-        percentage: percentage
-      }
+        percentage: percentage,
+        cellphone:  cellphone
+      }.reject { |k, v| v.nil? }
 
       put("policies/#{policy_id}/beneficiaries", data)
     end
 
+    # List policies
+    #
+    # @param [String] id_number The National ID Number of the policyholder (optional)
+    # @return [Array<Hash>]
+    #
+    # @example
+    #   client.list_policies(id_number: "8704094800082")
+    #
     def list_policies(id_number: nil)
       query = id_number ? {id_number: id_number} : nil
 
       get(:policies, query)
     end
 
+    # Get a policy
+    #
+    # @param [String] id The unique identifier of the policy
+    # @return [Hash]
+    #
+    # @example
+    #   client.get_policy(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e")
+    #
     def get_policy(id:)
       get("policies/#{id}")
     end
 
+    # Cancel a policy
+    #
+    # @param [String] id The unique identifier of the policy
+    # @param [String] reason A reason for why this policy is being cancelled.
+    # @return [Hash]
+    #
+    # @example
+    #  client.cancel_policy(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e", reason: "Not needed anymore")
+    #
     def cancel_policy(id:, reason:)
       data = {reason: reason}
 
       post("policies/#{id}/cancel", data)
     end
 
+    # Update a policy.
+    # Currently, only updating the app_data object is supported
+    #
+    # @param [String] id The unique identifier of the policy
+    # @param [Hash] app_data An object containing additional custom data for the policy.
+    # @return [Hash]
+    #
+    # @example
+    #  app_data = {gadget_color: "Space Grey", has_screen_cover: true}
+    #  client.update_policy(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e", app_data: app_data)
+    #
     def update_policy(id:, app_data:)
       data = {app_data: app_data}
 
       patch("policies/#{id}", data)
     end
 
-    def replace_policy(id:, quote_package_id:)
-      data = {quote_package_id: quote_package_id}
-
-      post("policies/#{id}/replace", data)
-    end
-
+    # Update a policy's billing amount.
+    #
+    # @param [String] id The unique identifier of the policy
+    # @param [Integer] billing_amount The billing amount to be set on the policy in cents.
+    # @return [Hash]
+    #
+    # @example
+    #  client.update_policy_billing_amount(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e", billing_amount: 45000)
+    #
     def update_policy_billing_amount(id:, billing_amount:)
       data = {billing_amount: billing_amount}
 
       post("policies/#{id}/billing_amount", data)
     end
 
+    # List a policy's bebeficiaries
+    #
+    # @param [String] id The unique identifier of the policy
+    # @return [Array<Hash>]
+    #
+    # @example
+    #  client.list_policy_beneficiaries(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e")
+    #
     def list_policy_beneficiaries(id:)
       get("policies/#{id}/beneficiaries")
     end
 
+    # List all the events which are applicable to this policy.
+    #
+    # @param [String] id The unique identifier of the policy
+    # @return [Array<Hash>]
+    #
+    # @example
+    #  client.list_policy_events(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e")
+    #
     def list_policy_events(id:)
       get("policies/#{id}/events")
     end

data/lib/root_insurance/api/policy_holder.rb

@@ -1,5 +1,33 @@
 module RootInsurance::Api
   module PolicyHolder
+    # Create a policy holder
+    #
+    # @param [Hash] id Hash containing policyholder's identification number, type and country. See below for details.
+    # @param [String] first_name Policyholder's legal first name.
+    # @param [String] last_name Policyholder's legal last name.
+    # @param [String] email Policyholder's contact email address. (Optional)
+    # @param [String] date_of_birth The policyholder's date of birth in the format YYYYMMDD. This field may be omitted if the policyholder's id type is +id+.
+    # @param [Hash] cellphone Hash containing policyholder's cellphone number and country. See below for details. (Optional)
+    # @param [Hash] app_data A hash containing additional custom data for the policy holder.
+    # @return [Hash]
+    #
+    ## == ID
+    # [type (string or symbol)]   Either +:id+ or +:passport+
+    # [number (string)]   The id or passport number
+    # [country (string)]   The ISO Alpha-2 country code of the country of the id/passport number.
+    #
+    ## == Cellphone
+    # [number (string)]   The cellphone number
+    # [country (string)]   The ISO Alpha-2 country code of the country of the cellphone number.
+    #
+    # @example
+    #  client.create_policy_holder(
+    #    id:         {type: :id, number: "6801015800084", country: "ZA"},
+    #    first_name: 'Erlich',
+    #    last_name:  'Bachman',
+    #    email:      'erlich@avaito.com',
+    #    app_data:   {company: 'Aviato'})
+    #
     def create_policy_holder(id:, first_name:, last_name:, email: nil, date_of_birth: nil, cellphone: nil, app_data: nil)
       raise ArgumentError.new('id needs to be a hash') unless id.is_a? Hash
 
@@ -16,14 +44,58 @@ module RootInsurance::Api
       post(:policyholders, data)
     end
 
-    def list_policy_holders
-      get(:policyholders)
+    # List policy holders
+    #
+    # @param [Hash] id_number An optional ID or passport number to filter by.
+    # @param [Array<String, Symbol>, String, Symbol] included_objects An optional list, or single item, of underlying objects to include, e.g. +?include=policies+. Currently, only +policies+ is supported, which will include all policies owned by the policyholder.
+    # @return [Array<Hash>]
+    #
+    # @example
+    #   client.list_policy_holders(id_number: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e", included_objects: :policies)
+    def list_policy_holders(id_number: nil, included_objects: nil)
+      query = {
+        include:   format_included_objects(included_objects),
+        id_number: id_number
+      }.reject { |_, v| v.nil? }
+
+      get(:policyholders, query)
     end
 
-    def get_policy_holder(id:)
-      get("policyholders/#{id}")
+    # Get a policy holder
+    #
+    # @param [String] id The unique identifier of the policy holder
+    # @param [Array<String, Symbol>, String, Symbol] included_objects An optional list, or single item, of underlying objects to include, e.g. +?include=policies+. Currently, only +policies+ is supported, which will include all policies owned by the policyholder.
+    # @return [Hash]
+    #
+    # @example
+    #   client.get_policy_holder(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e", included_objects: :policies)
+    #
+    def get_policy_holder(id:, included_objects: nil)
+      query = {
+        include:   format_included_objects(included_objects),
+      }.reject { |_, v| v.nil? }
+
+      get("policyholders/#{id}", query)
     end
 
+    # Update a policy holder
+    #
+    # @param [String] id The unique identifier of the policy holder
+    # @param [String] email Policyholder's contact email address. (Optional)
+    # @param [Hash] cellphone Hash containing policyholder's cellphone number and country. See below for details. (Optional)
+    # @param [Hash] app_data A hash containing additional custom data for the policy holder.
+    # @return [Hash]
+    #
+    ## == Cellphone
+    # [number (string)]   The cellphone number
+    # [country (string)]   The ISO Alpha-2 country code of the country of the cellphone number.
+    #
+    # @example
+    #   client.update_policy_holders(
+    #     id: 'bf1ada91-eecb-4f47-9bfa-1258bb1e0055',
+    #     cellphone: {number: '07741011337', country: 'ZA'},
+    #     app_data:  {company: 'Pied Piper'})
+    #
     def update_policy_holder(id:, email: nil, cellphone: nil, app_data: nil)
       data = {
         email:     email,
@@ -34,8 +106,26 @@ module RootInsurance::Api
       patch("policyholders/#{id}", data)
     end
 
+    # List all the events which are applicable to this policy holder.
+    #
+    # @param [String] id The unique identifier of the policy holder
+    # @return [Array<Hash>]
+    #
+    # @example
+    #  client.list_policy_holder_events(id: "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e")
+    #
     def list_policy_holder_events(id:)
       get("policyholders/#{id}/events")
     end
+
+    private
+    def format_included_objects(included_objects)
+      case included_objects
+      when String, Symbol
+        included_objects
+      when Array
+        included_objects.join(",")
+      end
+    end
   end
 end

data/lib/root_insurance/api/quote.rb

@@ -1,5 +1,33 @@
 module RootInsurance::Api
   module Quote
+    # Create a quote
+    #
+    # @param [Hash] opts The quote details. Depending on +:type+, different options are available. Available types are: +:root_gadgets+, +:root_term+ and +:root_funeral+ See below for details
+    # @return [Hash]
+    #
+    ## == +:root_gadgets+
+    # [model_name (String)]   The model name of the gadget
+    #
+    ## == +:root_term+
+    # [cover_amount (Integer)]   Amount to cover, in cents. Should be between R100 000 and R5 000 000, inclusive.
+    # [cover_period (String or Symbol)]   Duration to cover: +:1_year+, +:2_years+, +:5_years+, +:10_years+, +:15_years+, +:20_years+ or +:whole_life+.
+    # [basic_income_per_month (Integer)]    Policyholder's basic monthly income, in cents.
+    # [education_status (String or Symbol)]    Policyholder’s education class: +:grade_12_no_matric+, +:grade_12_matric+, +:diploma_or_btech+, +:undergraduate_degree+ or +:professional_degree+
+    # [smoker (Boolean)]     Is the policyholder a smoker.
+    # [gender (String or Symbol)]    Gender of policyholder. Should be either +:male+ or +:female+.
+    # [age (Integer)]    Age of policyholder. Should be between 18 and 63, inclusive.
+    #
+    # == +:root_funeral+
+    # [cover_amount (Integer)]   Amount to cover, in cents. Should be between R10k and R50k, inclusive.
+    # [has_spouse (Boolean)]   Should a spouse also be covered.
+    # [number_of_children (Integer)]   Number of children to include in the policy. Should be between 0 and 8, inclusive
+    # [extended_family_ages (Array<Integer>)]   Ages of extended family members to cover.
+    #
+    # @example
+    #  client.create_quote(
+    #    type:       :root_gadgets,
+    #    model_name: 'iPhone 6s 64GB LTE')
+    #
     def create_quote(opts={})
       type = opts[:type]
 
@@ -15,6 +43,13 @@ module RootInsurance::Api
       end
     end
 
+    # List available gadget models
+    #
+    # @return [Array<Hash>]
+    #
+    # @example
+    #   client.list_gadget_models
+    #
     def list_gadget_models
       get('gadgets/models')
     end

data/lib/root_insurance/version.rb

@@ -1,3 +1,3 @@
 module RootInsurance
-  VERSION = "1.7.4"
+  VERSION = "1.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: root_insurance
 version: !ruby/object:Gem::Version
-  version: 1.7.4
+  version: 1.8.0
 platform: ruby
 authors:
 - Root Wealth
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-16 00:00:00.000000000 Z
+date: 2018-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty