social-security-calculator 0.0.6 → 0.0.8

package/LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright 2022 RYAN ANTKOWIAK, CHARLES MCNULTY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -4,14 +4,11 @@ TypeScript to calculate estimated Social Security Benefits
 
  This module will calculate your expected retirement benefits
  from Social Security given your annual earnings
- Inputs:
-           1) EarningsRecord -
-               Dictionary mapping a year to the amount of Social
-               Security eligible earnings in that particular year
 
-           2) NationalAverageWageIndexSeries -
-               Data pulled directly from the Social Security website for the
-               national average wage data
+ Input:
 
-Adapted from python originally written by Ryan Antkowiak (antkowiak@gmail.com) and updated by Kevin Fowlks (fowlk1kd@gmail.com)
+ Dictionary mapping a year to the amount of Social
+ Security eligible earnings in that particular year
 
+
+Adapted from python originally written by Ryan Antkowiak

package/lib/estimatedEarnings/index.js

@@ -0,0 +1,45 @@
+import { wageIndex, quickCalcProjections, taxableMaximum } from '../wage-index';
+const YOUTH_FACTOR = 8;
+const YOUTH_FACTOR_AGE = 21;
+const WORK_START_AGE = 18;
+const CURRENT_YEAR = new Date().getFullYear();
+export function getEstimatedEarnings(age, lastWage, lastYearWorked = CURRENT_YEAR, earningGrowthRate = 0) {
+    if (age <= 22) {
+        throw new Error('Age must be greater than 22');
+    }
+    if (lastYearWorked > CURRENT_YEAR) {
+        throw new Error('Last year worked cannot be in the future');
+    }
+    const workStartYear = CURRENT_YEAR - age + WORK_START_AGE;
+    const yearTurned22 = CURRENT_YEAR - age + YOUTH_FACTOR_AGE;
+    const wageResults = {};
+    for (let i = lastYearWorked; i >= workStartYear; i--) {
+        const year = i;
+        const nextYear = (i + 1);
+        const youthAdjustment = (i === yearTurned22 ? YOUTH_FACTOR : 1);
+        wageResults[year] = (i === lastYearWorked)
+            ? lastWage
+            : wageResults[nextYear] * getReductionFactor(i) / (1 + earningGrowthRate) / youthAdjustment;
+    }
+    // Cap wages at taxable maximum
+    Object.keys(wageResults).forEach(strYear => {
+        const year = parseInt(strYear);
+        const maxTaxable = taxableMaximum[year];
+        wageResults[year] = Math.min(wageResults[year], maxTaxable);
+    });
+    return wageResults;
+}
+function getReductionFactor(year) {
+    const allIndexes = Object.assign(Object.assign({}, wageIndex), quickCalcProjections);
+    const lastYear = year - 1;
+    const nextYear = year + 1;
+    if (year === CURRENT_YEAR && !allIndexes[lastYear]) {
+        throw new Error(`Wage index for previous year (${lastYear}) is required`);
+    }
+    if (year === CURRENT_YEAR) {
+        return 1;
+    }
+    else {
+        return (allIndexes[year] / allIndexes[nextYear]);
+    }
+}

package/lib/index.js

@@ -1,49 +1,120 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const wage_index_1 = require("./wage-index");
-function calc(earnings) {
-    const lookbackYears = 35;
-    const futureYearsFactor = 1;
+import { wageIndex } from './wage-index';
+export function calc(birthday, retirementDate, earnings) {
+    const AIME = calculateAIME(earnings);
+    const results = calcRetirementBenefit(birthday, retirementDate, AIME);
+    return results;
+}
+export function calcRetirementBenefit(birthday, retirementDate, AIME) {
+    const eclBirthDate = getEnglishCommonLawDate(birthday);
+    const fullRetirementMonths = getFullRetirementMonths(eclBirthDate);
+    const PIA = calculatePIA(AIME);
+    const benefitAt62 = calculateSocialSecurityReduction(PIA, 60);
+    const normalMonthlyBenefit = Math.floor(PIA);
+    const results = {
+        "AIME": AIME,
+        "NormalMonthlyBenefit": normalMonthlyBenefit,
+        "NormalAnnualBenefit": PIA * 12,
+        "ReducedMonthlyBenefit": benefitAt62,
+        "ReducedAnnualBenefit": benefitAt62 * 12,
+    };
+    return results;
+}
+function calculatePIA(AIME) {
+    const averageWageLastYear = Math.max(...Object.keys(wageIndex).map(val => parseInt(val)));
+    const wageIndexLastYear = wageIndex[averageWageLastYear];
     const bendPointDivisor = 9779.44;
-    const firstBendPointMultiplier = 180.0;
-    const secondBendPointMultiplier = 1085.0;
-    const averageWageLastYear = Math.max(...Object.keys(wage_index_1.wageIndex).map(val => parseInt(val)));
-    const firstBendPoint = Math.round(firstBendPointMultiplier * wage_index_1.wageIndex[averageWageLastYear] / bendPointDivisor);
-    const secondBendPoint = Math.round(secondBendPointMultiplier * wage_index_1.wageIndex[averageWageLastYear] / bendPointDivisor);
-    const wageIndexFactors = Object.entries(wage_index_1.wageIndex).reduce((acc, [i, val]) => ((acc[i] = 1 + (wage_index_1.wageIndex[averageWageLastYear] - val) / val) && acc), {});
-    const adjustedEarnings = Object.entries(earnings).reduce((acc, [i, val]) => ((acc[i] = val * (wageIndexFactors[i] || futureYearsFactor)) && acc), {});
-    const top35YearsEarnings = Object.values(adjustedEarnings)
-        .sort((a, b) => b - a) // sort the earnings from highest to lowest amount
-        .slice(0, lookbackYears) // grab the highest 35 earnings years
-        .reduce((partialSum, a) => partialSum + a, 0); // and finally sum them
-    const AIME = top35YearsEarnings / (12 * lookbackYears);
-    const normalMonthlyBenefit = (() => {
+    const firstBendPointMultiplier = 180;
+    const secondBendPointMultiplier = 1085;
+    // https://www.ssa.gov/oact/COLA/piaformula.html
+    // Per examples, bend points are rounded to the nearest dollar
+    const firstBendPoint = Math.round(firstBendPointMultiplier * wageIndexLastYear / bendPointDivisor);
+    const secondBendPoint = Math.round(secondBendPointMultiplier * wageIndexLastYear / bendPointDivisor);
+    // https://www.ssa.gov/OP_Home/handbook/handbook.07/handbook-0738.html
+    // Calculations that are not a multiple of 10 cents are rounded to the next lower multiple of 10 cents. For example, $100.18 is rounded down to $100.10.
+    const PIA = (() => {
         let monthlyBenefit = 0;
         if (AIME <= firstBendPoint) {
             monthlyBenefit = 0.9 * AIME;
         }
         else {
             if (AIME > firstBendPoint && AIME <= secondBendPoint) {
-                monthlyBenefit = 0.9 * firstBendPoint + 0.32 * (AIME - firstBendPoint);
+                monthlyBenefit = (0.9 * firstBendPoint) + (0.32 * (AIME - firstBendPoint));
             }
             else {
-                monthlyBenefit = 0.9 * firstBendPoint + 0.32 * (secondBendPoint - firstBendPoint) + 0.15 * (AIME - secondBendPoint);
+                monthlyBenefit = (0.9 * firstBendPoint) + (0.32 * (secondBendPoint - firstBendPoint)) + (0.15 * (AIME - secondBendPoint));
             }
         }
-        return Math.floor(monthlyBenefit * 10.0) / 10.0;
-        ;
+        return roundToFloorTenCents(monthlyBenefit);
     })();
-    const reducedMonthlyBenefit = Math.floor(((0.7 * normalMonthlyBenefit) * 10) / 10);
-    const results = {
-        "Top35YearsEarnings": top35YearsEarnings.toFixed(2),
-        "AIME": AIME.toFixed(2),
-        "FirstBendPoint": firstBendPoint.toFixed(2),
-        "SecondBendPoint": secondBendPoint.toFixed(2),
-        "NormalMonthlyBenefit": normalMonthlyBenefit.toFixed(2),
-        "NormalAnnualBenefit": (normalMonthlyBenefit * 12).toFixed(2),
-        "ReducedMonthlyBenefit": reducedMonthlyBenefit.toFixed(2),
-        "ReducedAnnualBenefit": (reducedMonthlyBenefit * 12).toFixed(2),
-    };
-    return results;
+    return PIA;
+}
+function calculateAIME(earnings) {
+    const lookbackYears = 35;
+    const averageWageLastYear = Math.max(...Object.keys(wageIndex).map(val => parseInt(val)));
+    const wageIndexLastYear = wageIndex[averageWageLastYear];
+    const futureYearsFactor = 1;
+    // calculate the wage index factors
+    const wageIndexFactors = Object.entries(wageIndex).reduce((acc, [i, val]) => ((acc[parseInt(i)] = 1 + (wageIndexLastYear - val) / val), acc), {});
+    // adjust the earnings according to the wage index factor,
+    // factor is 1 for any earnings record without a wage-factor
+    const adjustedEarnings = Object.entries(earnings).reduce((acc, [i, val]) => ((acc[parseInt(i)] = val * (wageIndexFactors[parseInt(i)] || futureYearsFactor)), acc), {});
+    const top35YearsEarningsArr = Object.values(adjustedEarnings)
+        .sort((a, b) => b - a) // sort the earnings from highest to lowest amount
+        .slice(0, lookbackYears); // grab the highest 35 earnings years
+    const top35YearsEarnings = top35YearsEarningsArr.reduce((partialSum, a) => partialSum + a, 0); // and finally sum them
+    // https://www.ssa.gov/oact/cola/Benefits.html
+    // "We then round the resulting average amount down to the next lower dollar amount"
+    const AIME = Math.floor(top35YearsEarnings / (12 * lookbackYears));
+    return AIME;
+}
+function calculateSocialSecurityReduction(amount, months) {
+    const first36Rate = 5 / 9 * 0.01; // 5/9 of 1%
+    const additionalRate = 5 / 12 * 0.01; // 5/12 of 1%
+    let reduction = 0;
+    if (months <= 36) {
+        reduction = months * first36Rate;
+    }
+    else {
+        // 36 months times 5/9 of 1 percent plus 24 months times 5/12 of 1 percent.
+        reduction = 36 * first36Rate + (months - 36) * additionalRate;
+    }
+    return amount - amount * reduction;
+}
+function roundToFloorTenCents(amount) {
+    // Convert the amount to fractional dimes
+    let dimes = amount * 10;
+    // floor to only whole dimes
+    dimes = Math.floor(dimes);
+    // Convert back to dollars and return
+    return (dimes / 10);
+}
+function getEnglishCommonLawDate(date) {
+    const year = date.getFullYear();
+    const month = date.getMonth();
+    const day = date.getDate();
+    const englishCommonLawDate = new Date(year, month, day - 1);
+    return englishCommonLawDate;
+}
+export function getFullRetirementMonths(commonLawBirthDate) {
+    const year = commonLawBirthDate.getFullYear();
+    switch (true) {
+        case (year >= 1943 && year <= 1954):
+            return 66 * 12;
+        case (year >= 1955 && year <= 1959):
+            const fra = ((year - 1954) * 2) + (66 * 12);
+            return fra;
+        case (year >= 1960):
+            return 67 * 12;
+        default:
+            throw new Error('Invalid birth year');
+    }
 }
-module.exports = calc;
+/*
+1943-1954 	66 	                48 	$750 	25.00% 	$350 	30.00%
+1955 	    66 and 2 months 	50 	$741 	25.83% 	$345 	30.83%
+1956 	    66 and 4 months 	52 	$733 	26.67% 	$341 	31.67%
+1957 	    66 and 6 months 	54 	$725 	27.50% 	$337 	32.50%
+1958 	    66 and 8 months 	56 	$716 	28.33% 	$333 	33.33%
+1959 	    66 and 10 months 	58 	$708 	29.17% 	$329 	34.17%
+1960+ 	    67 	                60 	$700 	30.00% 	$325 	35.00%
+*/

package/lib/model.js

@@ -0,0 +1 @@
+export {};

package/lib/parseStatement/index.js

@@ -0,0 +1,19 @@
+import xml2js from 'xml2js';
+import fs from 'fs/promises';
+const NS = 'OSSS';
+// strict false because attribute is unquoted: <osss:OnlineSocialSecurityStatementData xmlns:osss=http://ssa.gov/osss/schemas/2.0>
+// could fix the XML, but better to keep file unchanged so that we can drop in relacement files from SSA
+const parser = new xml2js.Parser({ strict: false });
+const supportedVersion = "http://ssa.gov/osss/schemas/2.0";
+async function getWages(fileName) {
+    const data = await fs.readFile(fileName);
+    const result = await parser.parseStringPromise(data);
+    const schema = result[`${NS}:ONLINESOCIALSECURITYSTATEMENTDATA`]['$'][`XMLNS:${NS}`];
+    if (schema !== supportedVersion) {
+        throw `${schema} is not supported (${supportedVersion})`;
+    }
+    const results = result[`${NS}:ONLINESOCIALSECURITYSTATEMENTDATA`][`${NS}:EARNINGSRECORD`][0][`${NS}:EARNINGS`];
+    const earnings = results.reduce((acc, earn) => (earn[`${NS}:FICAEARNINGS`][0] === '-1' ? acc : acc[earn['$'].STARTYEAR] = parseInt(earn[`${NS}:FICAEARNINGS`][0]), acc), {});
+    return earnings;
+}
+export default getWages;

package/lib/wage-index.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.wageIndex = void 0;
-const compound = require('compound-calc');
-exports.wageIndex = {
+// https://www.ssa.gov/OACT/COLA/awiseries.html
+export const wageIndex = {
     1951: 2799.16,
     1952: 2973.32,
     1953: 3139.44,
@@ -73,50 +70,91 @@ exports.wageIndex = {
     2018: 52145.8,
     2019: 54099.99,
     2020: 55628.6,
+    2021: 60575.07,
+    2022: 63795.13
 };
-const shortRangeIntermediate = {
-    2021: 58743.07,
-    2022: 62583.15,
-    2023: 65571.72,
-    2024: 68371.79,
-    2025: 71147.65,
-    2026: 73980.60,
-    2027: 76857.74,
-    2028: 79761.29,
-    2029: 82702.63,
-    2030: 85713.03,
-    2031: 88836.46,
+// retrieved from: view-source:https://www.ssa.gov/cgi-bin/benefit6.cgi
+export const quickCalcProjections = {
+    2023: 66488.13,
+    2024: 68981.33,
+    2025: 71780.09,
+    2026: 74731.71,
+    2027: 77792.60,
+    2028: 80925.73,
+    2029: 84188.76,
+    2030: 87555.49,
+    2031: 91041.35,
+    2032: 94479.84,
+    2033: 97957.36,
+    2034: 101547.32,
+    2035: 105266.09,
+    2036: 109120.74,
+    2037: 113117.42,
+    2038: 117250.70,
+    2039: 121537.41,
+    2040: 125958.59,
+    2041: 130512.20,
+    2042: 135207.00,
+    2043: 140051.90,
+    2044: 145045.39,
+    2045: 150193.68,
+    2046: 155501.36,
+    2047: 160999.09,
+    2048: 166686.37,
+    2049: 172576.11,
 };
-const longRangeIntermediate = {
-    2035: 102530.83,
-    2040: 122417.01,
-    2045: 145582.26,
-    2050: 172887.64,
-    2055: 205634.94,
-    2060: 244870.78,
-    2065: 291767.28,
-    2070: 347552.77,
-    2075: 413851.91,
-    2080: 492391.60,
-    2085: 585488.00,
-    2090: 696610.41,
-    2095: 829710.10,
-    2100: 988243.75,
+export const taxableMaximum = {
+    1972: 9000,
+    1973: 10800,
+    1974: 13200,
+    1975: 14100,
+    1976: 15300,
+    1977: 16500,
+    1978: 17700,
+    1979: 22900,
+    1980: 25900,
+    1981: 29700,
+    1982: 32400,
+    1983: 35700,
+    1984: 37800,
+    1985: 39600,
+    1986: 42000,
+    1987: 43800,
+    1988: 45000,
+    1989: 48000,
+    1990: 51300,
+    1991: 53400,
+    1992: 55500,
+    1993: 57600,
+    1994: 60600,
+    1995: 61200,
+    1996: 62700,
+    1997: 65400,
+    1998: 68400,
+    1999: 72600,
+    2000: 76200,
+    2001: 80400,
+    2002: 84900,
+    2003: 87000,
+    2004: 87900,
+    2005: 90000,
+    2006: 94200,
+    2007: 97500,
+    2008: 102000,
+    2009: 106800,
+    2010: 106800,
+    2011: 106800,
+    2012: 110100,
+    2013: 113700,
+    2014: 117000,
+    2015: 118500,
+    2016: 118500,
+    2017: 127200,
+    2018: 128400,
+    2019: 132900,
+    2020: 137700,
+    2021: 142800,
+    2022: 147000,
+    2023: 160200,
+    2024: 168600,
 };
-const fillBlanks = (vals) => Object.entries(vals).reduce((acc, [year, P], index, arr) => {
-    let thing;
-    if (arr[index + 1]) {
-        const [nextYear, A] = arr[index + 1];
-        const t = parseInt(nextYear) - parseInt(year);
-        const r = Math.pow((A / P), (1 / t)) - 1;
-        const vals = compound(P, 0, t, r).result.slice(0, -1);
-        const ret = vals.reduce((accx, cur, i) => ((accx[(parseInt(year) + i).toString()] = cur) && accx), {});
-        thing = Object.assign(Object.assign({}, acc), ret);
-    }
-    else {
-        thing = Object.assign(Object.assign({}, acc), { [year]: P });
-    }
-    return thing;
-}, {});
-// console.log(fillBlanks(longRangeIntermediate));
-console.log(fillBlanks({ 2000: 38915, 2021: 108494 }));

package/package.json

@@ -1,29 +1,46 @@
 {
   "name": "social-security-calculator",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Calculate estimated Social Security Benefits",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js",
+    "./parseStatement": "./lib/parseStatement/index.js",
+    "./estimatedEarnings": "./lib/estimatedEarnings/index.js"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "build": "tsc"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cmcnulty/SocialSecurityCalculator.git"
   },
-  "keywords": [],
+  "keywords": [
+    "calculator",
+    "social",
+    "security",
+    "ssi"
+  ],
   "author": "",
-  "license": "ISC",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/cmcnulty/SocialSecurityCalculator/issues"
   },
   "homepage": "https://github.com/cmcnulty/SocialSecurityCalculator#readme",
   "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/jest": "^29.5.8",
+    "@types/xml2js": "^0.4.11",
+    "compound-calc": "^4.0.3",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.1",
     "typescript": "^4.8.3"
   },
   "dependencies": {
-    "compound-calc": "^2.0.0"
+    "xml2js": "^0.6.2"
   },
   "files": [
     "lib"

package/lib/index.d.ts

@@ -1,15 +0,0 @@
-export = calc;
-declare function calc(earnings: any): {
-    Top35YearsEarnings: any;
-    AIME: string;
-    FirstBendPoint: string;
-    SecondBendPoint: string;
-    NormalMonthlyBenefit: string;
-    NormalAnnualBenefit: string;
-    ReducedMonthlyBenefit: string;
-    ReducedAnnualBenefit: string;
-};
-declare namespace calc {
-    export { __esModule };
-}
-declare const __esModule: boolean;

package/lib/package.bak

@@ -1,31 +0,0 @@
-{
-  "name": "social-security-calculator",
-  "version": "0.0.5",
-  "description": "Calculate estimated Social Security Benefits",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "files": [
-    "**/*"
-  ],
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "build": "tsc"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/cmcnulty/SocialSecurityCalculator.git"
-  },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/cmcnulty/SocialSecurityCalculator/issues"
-  },
-  "homepage": "https://github.com/cmcnulty/SocialSecurityCalculator#readme",
-  "devDependencies": {
-    "typescript": "^4.8.3"
-  },
-  "dependencies": {
-    "compound-calc": "^2.0.0"
-  }
-}