singapore_cpf_calculator 1.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c10a9da895045667814bc945fe76c308fa58f61a
+  data.tar.gz: 0c7815f181658ee0511bdf631822ef6c4871164f
+SHA512:
+  metadata.gz: d7bd99c5b7bdd11616e9773158838aa03f293e61a3d5555165185702ac423ddb1a4fa5bcc48ff4fc86dd7091f370c698f3e75aaf4f0c31fb2f708d66486fa363
+  data.tar.gz: 976dec1337b458a379b4478b3db71e3ca7451ecdf1d5998db3bfc47769adfed4558036f87f1fbe0d7d1933f9e8cd951e15f87096693af7ed193a75602289f865

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in singapore_cpf_calculator.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014, PayrollHero PTE. Ltd. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that
+the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the
+following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
+following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or
+promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.

data/README.md

@@ -0,0 +1,97 @@
+# SingaporeCPFCalculator
+
+[![Gem Version](https://badge.fury.io/rb/singapore_cpf_calculator.svg)](http://badge.fury.io/rb/singapore_cpf_calculator)
+[![Code Climate](https://codeclimate.com/github/payrollhero/singapore_cpf_calculator/badges/gpa.svg)](https://codeclimate.com/github/payrollhero/singapore_cpf_calculator)
+[![Test Coverage](https://codeclimate.com/github/payrollhero/singapore_cpf_calculator/badges/coverage.svg)](https://codeclimate.com/github/payrollhero/singapore_cpf_calculator)
+
+[![Circle CI](https://circleci.com/gh/payrollhero/singapore_cpf_calculator.png?style=badge)](https://circleci.com/gh/payrollhero/singapore_cpf_calculator)
+
+`SingaporeCPFCalculator` is the gem PayrollHero.com created and use to calculate for Singapore's
+Central Provident Fund (CPF) contributions.
+
+## Support
+
+  * [Year 2015](http://mycpf.cpf.gov.sg/NR/rdonlyres/9F38419D-1342-4426-820E-32BA8FDE5C6D/0/CPFContributionandAllocationRatesfrom1January2015.pdf)
+    * Singapore Citizens or Singapore Permanent Residents (3rd Year Onwards)
+    * Singapore Permanent Residents (SPRs) during 1st Year of SPR Status
+      * Graduated Employer & Employee (G/G) Contribution Rate
+      * Full Employer & Graduated Employee (F/G) Contribution Rate
+    * Singapore Permanent Residents (SPRs) during 2nd Year of SPR Status
+      * Graduated Employer & Employee (G/G) Contribution Rate
+      * Full Employer & Graduated Employee (F/G) Contribution Rate
+  * Year 2014
+    * [Singapore Citizens or Singapore Permanent Residents (3rd Year Onwards)](http://mycpf.cpf.gov.sg/NR/rdonlyres/B169395E-335C-479C-AB6E-74BA5FBEC6F0/0/CPFconratetable_from1Jan2014_forPTEandNPEN_SC.pdf)
+    * Singapore Permanent Residents (SPRs) during 2nd Year of SPR Status
+      * [Graduated Employer & Employee (G/G)](http://mycpf.cpf.gov.sg/NR/rdonlyres/E49C4AFE-8048-4A49-8672-B59D1D34A90B/0/CPFconratetable_from1Jan2014_forPTEandNPEN_2GG.pdf)
+      * [Full Employer & Graduated Employee (F/G)](http://mycpf.cpf.gov.sg/NR/rdonlyres/598CEDE2-61D0-44CE-9E96-AAD2FFCE4449/0/CPFconratetable_from1Jan2014_forPTEandNPEN_2FG.pdf)
+    * Singapore Permanent Residents (SPRs) during 1st Year of SPR Status
+      * [Graduated Employer & Employee (G/G)](http://mycpf.cpf.gov.sg/NR/rdonlyres/90D2E0D8-9922-4CAD-87A6-94D6893954E8/0/CPFconratetable_from1Jan2014_forPTEandNPEN_1GG.pdf)
+      * [Full Employer & Graduated Employee (F/G)](http://mycpf.cpf.gov.sg/NR/rdonlyres/32EB83C4-9472-4D25-93D6-D760F486DBE3/0/CPFconratetable_from1Jan2014_forPTEandNPEN_1FG.pdf)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'singapore_cpf_calculator'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install singapore_cpf_calculator
+
+## Usage
+
+Use {SingaporeCPFCalculator.calculate} to calculate for CPF contribution. The method return a
+{SingaporeCPFCalculator::CPFContribution} object responding to {SingaporeCPFCalculator::CPFContribution#employee},
+{SingaporeCPFCalculator::CPFContribution#employer} and {SingaporeCPFCalculator::CPFContribution#total}.
+
+```ruby
+  require "singapore_cpf_calculator"
+
+  result = SingaporeCPFCalculator.calculate date: Date.new(2014, 11, 15),
+                                            birthdate: Date.new(1982, 2, 18),
+                                            residency_status: "permanent_resident",
+                                            spr_start_date: Date.new(2014, 11, 15),
+                                            ordinary_wages: 700.00,
+                                            additional_wages: 252.00,
+                                            employee_contribution_type: "full",
+                                            employer_contribution_type: "full"
+
+  result # => #<SingaporeCPFCalculator::CPFContribution ...>
+  result.employee # => 190.00
+  result.employer # => 153.00
+  result.total # => 343.00
+```
+
+The following parameters needs to be specified:
+
+  * **date** : current date when the CPF is being calculated for
+  * **birthdate** : birthdate of the employee
+  * **residency\_status** : residency status of the employee
+    * accepted values : `"citizen"`, `"permanent_resident"`
+  * **spr\_start\_date** : date when Singapore Permanent Residency (SPR) started
+    * notes:
+      * this affects how the employee is classified into SPR1, SPR2 or SPR3
+      * required if the `residency_status` is `permanent_resident`
+    * see: [Year of Singapore Permanent Resident (SPR) Status](http://mycpf.cpf.gov.sg/NR/exeres/3D0D66F9-0085-4FD5-9CB5-35B55C0ADA53,frameless.htm)
+  * **ordinary_wages** :
+    * see : [ordinary wages definition](http://mycpf.cpf.gov.sg/NR/exeres/24537890-6D8E-495E-80D5-E5EFEFCA1905,frameless.htm)
+  * **additional_wages** :
+    * see : [additional wages definition](http://mycpf.cpf.gov.sg/Employers/Employers_Guide_to_CPF/Glossary/Glossary_Additional_Wages.htm)
+  * **employee\_contribution\_type** : type of rates to use for the employee's contribution
+    * accepted values : `"full"`, `"graduated"`
+    * note: *full* rates is not supported if the employer's contribution type is *graduated*
+  * **employer\_contribution\_type** : type of rates to use
+    * accepted values : `"full"`, `"graduated"` type of rates to use for the employer's contribution
+    * note: *graduated* rates is not supported if the employee's contribution type is *full*
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/singapore_cpf_calculator/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/circle.yml

@@ -0,0 +1,3 @@
+machine:
+  ruby:
+    version: 2.1.2

data/lib/singapore_cpf_calculator.rb

@@ -0,0 +1,125 @@
+require "singapore_cpf_calculator/version"
+require "active_support/all"
+
+module SingaporeCPFCalculator
+
+  class << self
+    # @example:
+    #   result = SingaporeCPFCalculator.calculate age: 32,
+    #                                             date: Date.new(2014, 11, 15),
+    #                                             residency_status: "permanent_resident",
+    #                                             spr_start_date: Date.new(2014, 11, 15),
+    #                                             ordinary_wages: 700.00,
+    #                                             additional_wages: 252.00,
+    #                                             employee_contribution_type: "full",
+    #                                             employer_contribution_type: "full"
+    #
+    #   result # => #<SingaporeCPFCalculator::CPFContribution ...>
+    #   result.employee # => 190.00
+    #   result.employer # => 153.00
+    #   result.total # => 343.00
+    #
+    #
+    # @param [Date] date: relevant date when the CPF contribution is being calculated
+    # @param [Date] birthdate:
+    # @param [String] residency_status: ["citizen", "permanent_resident"]
+    # @param [Date] spr_start_date: date when the employee became a Singapore permanent resident
+    # @param [String] employee_contribution_type: ["full", "graduated"]
+    # @param [String] employer_contribution_type: ["full", "graduated"]
+    # @param [BigDecimal] ordinary_wages:
+    #   Ordinary wages are wages due or granted in respect of employment and include allowances (e.g.
+    #   food allowance and overtime payments) earned by an employee in the month and payable before
+    #   the due date for payment of CPF contributions for that month.
+    # @param [BigDecimal] additional_wages:
+    #   Additional wages are wage supplements which are not granted wholly and exclusively for the
+    #   month, such as annual bonus and leave pay. These and other incentive payments may be made at
+    #   intervals of more than a month.
+    #
+    # @return [CPFContribution]
+    def calculate(
+      date:,
+      birthdate:,
+      residency_status:,
+      spr_start_date: nil,
+      ordinary_wages:,
+      additional_wages:,
+      employee_contribution_type: nil,
+      employer_contribution_type: nil
+    )
+      validate_params date: date,
+                      employee_contribution_type: employee_contribution_type,
+                      employer_contribution_type: employer_contribution_type,
+                      residency_status: residency_status,
+                      spr_start_date: spr_start_date
+
+      module_for_date(date).
+        module_for_residency(
+          status: residency_status,
+          spr_start_date: spr_start_date,
+          current_date: date,
+          employee_contribution_type: employee_contribution_type,
+          employer_contribution_type: employer_contribution_type
+        ).calculator_for(date, birthdate: birthdate).
+        calculate ordinary_wages: ordinary_wages, additional_wages: additional_wages
+    end
+
+    private
+
+    def validate_params(
+      date:,
+      employee_contribution_type:,
+      employer_contribution_type:,
+      residency_status:,
+      spr_start_date:
+    )
+      if residency_status == "permanent_resident"
+        raise ArgumentError, "spr_start_date: must be set" if spr_start_date.nil?
+        if contribution_types_required?(date, spr_start_date)
+          if employee_contribution_type.nil?
+            raise ArgumentError, "employee_contribution_type: must be set"
+          end
+          if employer_contribution_type.nil?
+            raise ArgumentError, "employer_contribution_type: must be set"
+          end
+        end
+      end
+
+      unless ["citizen", "permanent_resident"].include? residency_status
+        raise ArgumentError, "unsupported residency status: #{ residency_status }"
+      end
+    end
+
+    def contribution_types_required?(date, spr_start_date)
+      date <= (spr_start_date + 2.years)
+    end
+
+    def module_for_date(date)
+      date_modules.find { |mod| mod.applies_to? date } or
+        raise ArgumentError, "could not find date module for #{ date }"
+    end
+
+    def date_modules
+      [
+        Year2014,
+        Year2015,
+      ]
+    end
+  end
+
+end
+
+require_relative "singapore_cpf_calculator/cpf_contribution"
+require_relative "singapore_cpf_calculator/base_calculator"
+require_relative "singapore_cpf_calculator/before_spr"
+require_relative "singapore_cpf_calculator/age_group"
+require_relative "singapore_cpf_calculator/spr_status"
+require_relative "singapore_cpf_calculator/requirements"
+require_relative "singapore_cpf_calculator/year_common"
+require_relative "singapore_cpf_calculator/residency_module_common"
+require_relative "singapore_cpf_calculator/citizen_or_spr_3_common"
+require_relative "singapore_cpf_calculator/spr_1_fg_common"
+require_relative "singapore_cpf_calculator/spr_1_gg_common"
+require_relative "singapore_cpf_calculator/spr_2_fg_common"
+require_relative "singapore_cpf_calculator/spr_2_gg_common"
+require_relative "singapore_cpf_calculator/year_2014"
+require_relative "singapore_cpf_calculator/year_2015"

data/lib/singapore_cpf_calculator/age_group.rb

@@ -0,0 +1,71 @@
+module SingaporeCPFCalculator
+
+  # The contribution rates in respect of an employee above 35, 50, 55, 60 or 65 years of age
+  # shall be applied from the first day of the month after the month of his 35th, 50th, 55th,
+  # 60th or 65th birthday.
+  class AgeGroup
+
+    class << self
+
+      # @param [Date] current_date
+      # @param [Date] birthdate
+      # @return [Symbol] the symbol representation of the age group
+      #   - :group_50_years_and_below
+      #   - :group_above_50_to_55_years
+      #   - :group_above_55_to_60_years
+      #   - :group_above_60_to_65_years
+      #   - :group_above_65_years
+      def get(current_date, birthdate:)
+        new(current_date, birthdate: birthdate).get
+      end
+    end
+
+    # @param [Date] current_date
+    # @param [Date] birthdate:
+    def initialize(current_date, birthdate:)
+      @current_date = current_date
+      @birthdate = birthdate
+    end
+
+    # @return [Symbol] the symbol representation of the age group
+    #   - :group_50_years_and_below
+    #   - :group_above_50_to_55_years
+    #   - :group_above_55_to_60_years
+    #   - :group_above_60_to_65_years
+    #   - :group_above_65_years
+    def get
+      case
+      when age < 50
+        :group_50_years_and_below
+      when 50 <= age && age < 55
+        :group_above_50_to_55_years
+      when 55 <= age && age < 60
+        :group_above_55_to_60_years
+      when 60 <= age && age < 65
+        :group_above_60_to_65_years
+      else # 65 <= age
+        :group_above_65_years
+      end
+    end
+
+    private
+
+    attr_reader :current_date, :birthdate
+
+    def age
+      @age ||= effective_age
+    end
+
+    def effective_age
+      age_by_year = current_date.year - birthdate.year
+
+      if current_date.month > birthdate.month
+        age_by_year
+      else
+        age_by_year - 1
+      end
+    end
+
+  end
+
+end

data/lib/singapore_cpf_calculator/base_calculator.rb

@@ -0,0 +1,114 @@
+module SingaporeCPFCalculator
+  # Base class for CPF calculators.
+  class BaseCalculator
+
+    class << self
+      # @param [Fixnum] age
+      # @return [true, false] returns true if the calculator applies to the employee's age.
+      def applies_to?(date, birthdate:)
+        AgeGroup.get(date, birthdate: birthdate) == required_age_group
+      end
+
+      # @param [BigDecimal] ordinary_wages:
+      #   Ordinary wages are wages due or granted in respect of employment and include allowances (e.g.
+      #   food allowance and overtime payments) earned by an employee in the month and payable before
+      #   the due date for payment of CPF contributions for that month.
+      # @param [BigDecimal] additional_wages:
+      #   Additional wages are wage supplements which are not granted wholly and exclusively for the
+      #   month, such as annual bonus and leave pay. These and other incentive payments may be made at
+      #   intervals of more than a month.
+      #
+      # @return [Hash] returns the total, employee, employer amounts for the CPF contribution
+      def calculate(ordinary_wages:, additional_wages:)
+        new(ordinary_wages: ordinary_wages, additional_wages: additional_wages).calculate
+      end
+
+      private
+
+      def required_age_group
+        raise NotImplementedError, "sub classes needs to implement .required_age_group"
+      end
+    end
+
+    def initialize(ordinary_wages:, additional_wages:)
+      @ordinary_wages = ordinary_wages
+      @additional_wages = additional_wages
+    end
+
+    # @return [Hash] returns the total, employee, employer amounts for the CPF contribution
+    def calculate
+      CPFContribution.new total: total_contribution,
+                          employee: employee_contribution
+    end
+
+    private
+
+    attr_reader :ordinary_wages, :additional_wages
+
+    def total_contribution
+      @total_contribution ||= calculated_total_contribution.round(0, :half_up)
+    end
+
+    def employee_contribution
+      @employee_contribution ||= calculated_employee_contribution.round(0, :truncate)
+    end
+
+    def employer_contribution
+      @employer_contribution ||= total_contribution - employee_contribution
+    end
+
+    def total_wages
+      ordinary_wages + additional_wages
+    end
+
+    def calculated_total_contribution
+      case
+      when total_wages <= d("50.00")
+        d("0.0")
+      when total_wages <= d("500.00")
+        d(tc_rate_1) * total_wages
+      when total_wages < d("750.0000")
+        (d(tc_rate_1) * total_wages) + (d(adjustment_rate) * (total_wages - d("500.00")))
+      else # >= $750
+        (d(tc_rate_2) * capped_ordinary_wages) + (d(tc_rate_2) * additional_wages)
+      end
+    end
+
+    def calculated_employee_contribution
+      case
+      when total_wages < d("500.0000")
+        d("0.0")
+      when total_wages < d("750.0000")
+        (d(adjustment_rate) * (total_wages - d("500.00")))
+      else # >= $750
+        (d(ec_rate) * capped_ordinary_wages) + (d(ec_rate) * additional_wages)
+      end
+    end
+
+    def tc_rate_1
+      raise NotImplementedError, "sub classes needs to implement #tc_rate_1"
+    end
+
+    def tc_rate_2
+      raise NotImplementedError, "sub classes needs to implement #tc_rate_2"
+    end
+
+    def ec_rate
+      raise NotImplementedError, "sub classes needs to implement #ec_rate"
+    end
+
+    def adjustment_rate
+      raise NotImplementedError, "sub classes needs to implement #adjustment_rate"
+    end
+
+    def capped_ordinary_wages
+      raise NotImplementedError, "sub classes needs to implement #capped_ordinary_wages"
+    end
+
+    # precision helper
+    def d(val)
+      BigDecimal.new val
+    end
+
+  end
+end