@markcolabs/mcp 0.2.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +128 -205
- package/dist/index.d.ts +9 -23
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +51 -186
- package/dist/index.js.map +1 -1
- package/package.json +21 -12
- package/dist/disclaimers/ymyl.d.ts +0 -16
- package/dist/disclaimers/ymyl.d.ts.map +0 -1
- package/dist/disclaimers/ymyl.js +0 -20
- package/dist/disclaimers/ymyl.js.map +0 -1
- package/dist/engines/compoundInterest.d.ts +0 -75
- package/dist/engines/compoundInterest.d.ts.map +0 -1
- package/dist/engines/compoundInterest.js +0 -74
- package/dist/engines/compoundInterest.js.map +0 -1
- package/dist/engines/data/federalTax.d.ts +0 -47
- package/dist/engines/data/federalTax.d.ts.map +0 -1
- package/dist/engines/data/federalTax.js +0 -111
- package/dist/engines/data/federalTax.js.map +0 -1
- package/dist/engines/data/irs2026.d.ts +0 -30
- package/dist/engines/data/irs2026.d.ts.map +0 -1
- package/dist/engines/data/irs2026.js +0 -30
- package/dist/engines/data/irs2026.js.map +0 -1
- package/dist/engines/data/ssa.d.ts +0 -39
- package/dist/engines/data/ssa.d.ts.map +0 -1
- package/dist/engines/data/ssa.js +0 -55
- package/dist/engines/data/ssa.js.map +0 -1
- package/dist/engines/mortgage.d.ts +0 -70
- package/dist/engines/mortgage.d.ts.map +0 -1
- package/dist/engines/mortgage.js +0 -60
- package/dist/engines/mortgage.js.map +0 -1
- package/dist/engines/paycheck.d.ts +0 -93
- package/dist/engines/paycheck.d.ts.map +0 -1
- package/dist/engines/paycheck.js +0 -113
- package/dist/engines/paycheck.js.map +0 -1
- package/dist/engines/retirement401k.d.ts +0 -109
- package/dist/engines/retirement401k.d.ts.map +0 -1
- package/dist/engines/retirement401k.js +0 -130
- package/dist/engines/retirement401k.js.map +0 -1
- package/dist/engines/socialSecurity.d.ts +0 -63
- package/dist/engines/socialSecurity.d.ts.map +0 -1
- package/dist/engines/socialSecurity.js +0 -139
- package/dist/engines/socialSecurity.js.map +0 -1
- package/dist/envelope.d.ts +0 -76
- package/dist/envelope.d.ts.map +0 -1
- package/dist/envelope.js +0 -34
- package/dist/envelope.js.map +0 -1
- package/dist/shared/bounds.d.ts +0 -83
- package/dist/shared/bounds.d.ts.map +0 -1
- package/dist/shared/bounds.js +0 -121
- package/dist/shared/bounds.js.map +0 -1
- package/dist/tools/compoundInterest.d.ts +0 -48
- package/dist/tools/compoundInterest.d.ts.map +0 -1
- package/dist/tools/compoundInterest.js +0 -107
- package/dist/tools/compoundInterest.js.map +0 -1
- package/dist/tools/mortgage.d.ts +0 -51
- package/dist/tools/mortgage.d.ts.map +0 -1
- package/dist/tools/mortgage.js +0 -112
- package/dist/tools/mortgage.js.map +0 -1
- package/dist/tools/paycheck.d.ts +0 -54
- package/dist/tools/paycheck.d.ts.map +0 -1
- package/dist/tools/paycheck.js +0 -122
- package/dist/tools/paycheck.js.map +0 -1
- package/dist/tools/retirement401k.d.ts +0 -85
- package/dist/tools/retirement401k.d.ts.map +0 -1
- package/dist/tools/retirement401k.js +0 -141
- package/dist/tools/retirement401k.js.map +0 -1
- package/dist/tools/socialSecurity.d.ts +0 -51
- package/dist/tools/socialSecurity.d.ts.map +0 -1
- package/dist/tools/socialSecurity.js +0 -117
- package/dist/tools/socialSecurity.js.map +0 -1
- package/dist/util/zod-to-json-schema.d.ts +0 -28
- package/dist/util/zod-to-json-schema.d.ts.map +0 -1
- package/dist/util/zod-to-json-schema.js +0 -98
- package/dist/util/zod-to-json-schema.js.map +0 -1
|
@@ -1,109 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* 401(k) projection engine — lifted from
|
|
3
|
-
* site/src/pages/401k-retirement-calculator/401k-retirement-calculator.js
|
|
4
|
-
* (functions `calculateEmployerMatch`, `calculateFutureValue`,
|
|
5
|
-
* `generateYearlyBreakdown`, `getIRSLimit`, `getCatchUpAmount`,
|
|
6
|
-
* `calculate401kResults`).
|
|
7
|
-
*
|
|
8
|
-
* Per ADR-0039 § 5 (Calc-Engine Lift Pattern):
|
|
9
|
-
* - Pure synchronous functions of inputs → results. No DOM, no fetch.
|
|
10
|
-
* - ENGINE_VERSION bumps when math changes.
|
|
11
|
-
* - Parity tests at packages/mcp/test/parity/retirement401k.test.ts gate this
|
|
12
|
-
* engine against the source site calculator JS.
|
|
13
|
-
*
|
|
14
|
-
* MCP-side enhancement on top of the lift: the kickoff-defined input
|
|
15
|
-
* `annualSalaryGrowthPercent` is honored in this engine. The site engine
|
|
16
|
-
* applies a *flat* annual contribution; here we step year-by-year so each
|
|
17
|
-
* year's employee contribution + employer match scales with the cumulative
|
|
18
|
-
* salary growth. When `annualSalaryGrowthPercent === 0` the math is identical
|
|
19
|
-
* to the site engine (parity test "happy path" covers this).
|
|
20
|
-
*
|
|
21
|
-
* Math reference (year-by-year, mirroring the site's Math.pow form when growth=0):
|
|
22
|
-
* contrib_year_i = annualSalary * (1 + g)^i * (employeePct/100)
|
|
23
|
-
* (capped per IRS limit)
|
|
24
|
-
* match_year_i = annualSalary * (1 + g)^i * (matchedPct/100) * (employerMatchPct/100)
|
|
25
|
-
* balance_year_i = balance_year_{i-1} * (1 + r) + contrib_year_i + match_year_i
|
|
26
|
-
* balance_year_0 = currentBalance
|
|
27
|
-
*
|
|
28
|
-
* IRS limits: per IRS Notice 2025-67 (2026) — see engines/data/irs2026.ts.
|
|
29
|
-
*/
|
|
30
|
-
/**
|
|
31
|
-
* SemVer of the 401(k) projection engine. Per ADR-0039 § 5 (reaffirmed in
|
|
32
|
-
* ADR-0041 Position #4a): major bump = math change; minor = additive output;
|
|
33
|
-
* patch = numerical correction. NOT bumped for cosmetic refactors.
|
|
34
|
-
* - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
|
|
35
|
-
* - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
|
|
36
|
-
* Math unchanged.
|
|
37
|
-
*/
|
|
38
|
-
export declare const ENGINE_VERSION = "1.0.0";
|
|
39
|
-
/** Inputs to the 401(k) projection engine. */
|
|
40
|
-
export interface Retirement401kProjectionInput {
|
|
41
|
-
/** Current 401(k) balance, USD. */
|
|
42
|
-
currentBalance: number;
|
|
43
|
-
/** Current annual gross salary, USD. */
|
|
44
|
-
annualSalary: number;
|
|
45
|
-
/** Employee contribution as percent of salary (0-100). */
|
|
46
|
-
contributionPercent: number;
|
|
47
|
-
/**
|
|
48
|
-
* Employer match percent (0-100). Example: 50 means employer contributes
|
|
49
|
-
* $0.50 for each $1 the employee contributes, up to the match cap.
|
|
50
|
-
*/
|
|
51
|
-
employerMatchPercent: number;
|
|
52
|
-
/**
|
|
53
|
-
* Cap on how much of the employee's contribution percent the employer
|
|
54
|
-
* matches. Example: 6 means the employer matches up to 6% of salary.
|
|
55
|
-
*/
|
|
56
|
-
employerMatchLimitPercent: number;
|
|
57
|
-
/** Annual salary growth percent (0-20). 0 mirrors the site engine's flat-salary path. */
|
|
58
|
-
annualSalaryGrowthPercent: number;
|
|
59
|
-
/** Annual investment return percent (0-20). */
|
|
60
|
-
annualReturnPercent: number;
|
|
61
|
-
/** Current age (used for catch-up eligibility). */
|
|
62
|
-
currentAge: number;
|
|
63
|
-
/** Target retirement age (must be > currentAge). */
|
|
64
|
-
retirementAge: number;
|
|
65
|
-
/**
|
|
66
|
-
* Whether to enable catch-up contributions when eligible. Default true:
|
|
67
|
-
* if the user's age is in a catch-up window, apply the catch-up cap.
|
|
68
|
-
* Mirrors the site `catchUpToggle` form field semantics.
|
|
69
|
-
*/
|
|
70
|
-
catchUpEnabled?: boolean;
|
|
71
|
-
}
|
|
72
|
-
/** One row of the year-by-year projection table. */
|
|
73
|
-
export interface Retirement401kYearRow {
|
|
74
|
-
/** Years from start (1..yearsToRetirement). */
|
|
75
|
-
year: number;
|
|
76
|
-
/** Age at end of this year. */
|
|
77
|
-
age: number;
|
|
78
|
-
/** Employee contribution this year (after IRS cap), USD. */
|
|
79
|
-
employeeContribution: number;
|
|
80
|
-
/** Employer match this year, USD. */
|
|
81
|
-
employerMatch: number;
|
|
82
|
-
/** Investment growth credited this year, USD. */
|
|
83
|
-
growth: number;
|
|
84
|
-
/** Ending balance for this year, USD. */
|
|
85
|
-
endingBalance: number;
|
|
86
|
-
}
|
|
87
|
-
/** Result payload returned by the engine. */
|
|
88
|
-
export interface Retirement401kProjectionResult {
|
|
89
|
-
/** Final 401(k) balance at retirement age, USD. */
|
|
90
|
-
futureBalance: number;
|
|
91
|
-
/** Sum of all employee contributions over the projection, USD. */
|
|
92
|
-
totalContributions: number;
|
|
93
|
-
/** Sum of all employer match contributions over the projection, USD. */
|
|
94
|
-
employerContribTotal: number;
|
|
95
|
-
/** futureBalance − (currentBalance + totalContributions + employerContribTotal). */
|
|
96
|
-
growthEarned: number;
|
|
97
|
-
/** Year-by-year rows from year 1 to year yearsToRetirement. */
|
|
98
|
-
yearByYear: Retirement401kYearRow[];
|
|
99
|
-
}
|
|
100
|
-
/**
|
|
101
|
-
* Project a 401(k) balance year by year through retirement.
|
|
102
|
-
*
|
|
103
|
-
* Uses the same per-year accumulation pattern as the site's
|
|
104
|
-
* `generateYearlyBreakdown` / `calculateFutureValue` (compounded annual return,
|
|
105
|
-
* end-of-year contributions). Differs from the site only in honoring
|
|
106
|
-
* `annualSalaryGrowthPercent` per kickoff input list.
|
|
107
|
-
*/
|
|
108
|
-
export declare function projection(input: Retirement401kProjectionInput): Retirement401kProjectionResult;
|
|
109
|
-
//# sourceMappingURL=retirement401k.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"retirement401k.d.ts","sourceRoot":"","sources":["../../src/engines/retirement401k.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,8CAA8C;AAC9C,MAAM,WAAW,6BAA6B;IAC5C,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,yBAAyB,EAAE,MAAM,CAAC;IAClC,yFAAyF;IACzF,yBAAyB,EAAE,MAAM,CAAC;IAClC,+CAA+C;IAC/C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,MAAM,WAAW,8BAA8B;IAC7C,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AA4CD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,6BAA6B,GACnC,8BAA8B,CA2EhC"}
|
|
@@ -1,130 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* 401(k) projection engine — lifted from
|
|
3
|
-
* site/src/pages/401k-retirement-calculator/401k-retirement-calculator.js
|
|
4
|
-
* (functions `calculateEmployerMatch`, `calculateFutureValue`,
|
|
5
|
-
* `generateYearlyBreakdown`, `getIRSLimit`, `getCatchUpAmount`,
|
|
6
|
-
* `calculate401kResults`).
|
|
7
|
-
*
|
|
8
|
-
* Per ADR-0039 § 5 (Calc-Engine Lift Pattern):
|
|
9
|
-
* - Pure synchronous functions of inputs → results. No DOM, no fetch.
|
|
10
|
-
* - ENGINE_VERSION bumps when math changes.
|
|
11
|
-
* - Parity tests at packages/mcp/test/parity/retirement401k.test.ts gate this
|
|
12
|
-
* engine against the source site calculator JS.
|
|
13
|
-
*
|
|
14
|
-
* MCP-side enhancement on top of the lift: the kickoff-defined input
|
|
15
|
-
* `annualSalaryGrowthPercent` is honored in this engine. The site engine
|
|
16
|
-
* applies a *flat* annual contribution; here we step year-by-year so each
|
|
17
|
-
* year's employee contribution + employer match scales with the cumulative
|
|
18
|
-
* salary growth. When `annualSalaryGrowthPercent === 0` the math is identical
|
|
19
|
-
* to the site engine (parity test "happy path" covers this).
|
|
20
|
-
*
|
|
21
|
-
* Math reference (year-by-year, mirroring the site's Math.pow form when growth=0):
|
|
22
|
-
* contrib_year_i = annualSalary * (1 + g)^i * (employeePct/100)
|
|
23
|
-
* (capped per IRS limit)
|
|
24
|
-
* match_year_i = annualSalary * (1 + g)^i * (matchedPct/100) * (employerMatchPct/100)
|
|
25
|
-
* balance_year_i = balance_year_{i-1} * (1 + r) + contrib_year_i + match_year_i
|
|
26
|
-
* balance_year_0 = currentBalance
|
|
27
|
-
*
|
|
28
|
-
* IRS limits: per IRS Notice 2025-67 (2026) — see engines/data/irs2026.ts.
|
|
29
|
-
*/
|
|
30
|
-
import { LIMITS_401K_2026 } from "./data/irs2026.js";
|
|
31
|
-
/**
|
|
32
|
-
* SemVer of the 401(k) projection engine. Per ADR-0039 § 5 (reaffirmed in
|
|
33
|
-
* ADR-0041 Position #4a): major bump = math change; minor = additive output;
|
|
34
|
-
* patch = numerical correction. NOT bumped for cosmetic refactors.
|
|
35
|
-
* - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
|
|
36
|
-
* - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
|
|
37
|
-
* Math unchanged.
|
|
38
|
-
*/
|
|
39
|
-
export const ENGINE_VERSION = "1.0.0";
|
|
40
|
-
const ROUND = (v) => Math.round(v * 100) / 100;
|
|
41
|
-
/**
|
|
42
|
-
* IRS contribution cap for a given age, mirroring `getIRSLimit` in the site engine.
|
|
43
|
-
*/
|
|
44
|
-
function irsLimitForAge(age, catchUpEnabled) {
|
|
45
|
-
if (!catchUpEnabled ||
|
|
46
|
-
!Number.isFinite(age) ||
|
|
47
|
-
age < LIMITS_401K_2026.catchUpAge) {
|
|
48
|
-
return LIMITS_401K_2026.base;
|
|
49
|
-
}
|
|
50
|
-
if (age >= LIMITS_401K_2026.superCatchUpAgeStart &&
|
|
51
|
-
age <= LIMITS_401K_2026.superCatchUpAgeEnd) {
|
|
52
|
-
return LIMITS_401K_2026.totalWithSuperCatchUp;
|
|
53
|
-
}
|
|
54
|
-
return LIMITS_401K_2026.totalWithCatchUp;
|
|
55
|
-
}
|
|
56
|
-
/**
|
|
57
|
-
* Catch-up dollar amount for a given age, mirroring `getCatchUpAmount` in site engine.
|
|
58
|
-
*/
|
|
59
|
-
function catchUpForAge(age, catchUpEnabled) {
|
|
60
|
-
if (!catchUpEnabled ||
|
|
61
|
-
!Number.isFinite(age) ||
|
|
62
|
-
age < LIMITS_401K_2026.catchUpAge) {
|
|
63
|
-
return 0;
|
|
64
|
-
}
|
|
65
|
-
if (age >= LIMITS_401K_2026.superCatchUpAgeStart &&
|
|
66
|
-
age <= LIMITS_401K_2026.superCatchUpAgeEnd) {
|
|
67
|
-
return LIMITS_401K_2026.superCatchUp;
|
|
68
|
-
}
|
|
69
|
-
return LIMITS_401K_2026.catchUp;
|
|
70
|
-
}
|
|
71
|
-
/**
|
|
72
|
-
* Project a 401(k) balance year by year through retirement.
|
|
73
|
-
*
|
|
74
|
-
* Uses the same per-year accumulation pattern as the site's
|
|
75
|
-
* `generateYearlyBreakdown` / `calculateFutureValue` (compounded annual return,
|
|
76
|
-
* end-of-year contributions). Differs from the site only in honoring
|
|
77
|
-
* `annualSalaryGrowthPercent` per kickoff input list.
|
|
78
|
-
*/
|
|
79
|
-
export function projection(input) {
|
|
80
|
-
const { currentBalance, annualSalary, contributionPercent, employerMatchPercent, employerMatchLimitPercent, annualSalaryGrowthPercent, annualReturnPercent, currentAge, retirementAge, catchUpEnabled = true, } = input;
|
|
81
|
-
const years = Math.max(0, Math.floor(retirementAge - currentAge));
|
|
82
|
-
const r = annualReturnPercent / 100;
|
|
83
|
-
const g = annualSalaryGrowthPercent / 100;
|
|
84
|
-
// matchedPct = min(employee contribution %, employer cap %)
|
|
85
|
-
const matchedPct = Math.min(contributionPercent, employerMatchLimitPercent);
|
|
86
|
-
let balance = currentBalance;
|
|
87
|
-
let totalContributions = 0;
|
|
88
|
-
let employerContribTotal = 0;
|
|
89
|
-
const rows = [];
|
|
90
|
-
for (let i = 1; i <= years; i++) {
|
|
91
|
-
const ageThisYear = currentAge + i;
|
|
92
|
-
const salaryThisYear = annualSalary * Math.pow(1 + g, i - 1);
|
|
93
|
-
// Base employee contribution from salary %, plus catch-up if eligible.
|
|
94
|
-
let employeeContrib = salaryThisYear * (contributionPercent / 100) +
|
|
95
|
-
catchUpForAge(ageThisYear, catchUpEnabled);
|
|
96
|
-
// Cap at IRS limit for this year's age (catch-up windows shift over time).
|
|
97
|
-
const cap = irsLimitForAge(ageThisYear, catchUpEnabled);
|
|
98
|
-
if (employeeContrib > cap)
|
|
99
|
-
employeeContrib = cap;
|
|
100
|
-
// Employer match scales with salary, capped by employer-match limit %.
|
|
101
|
-
const employerMatch = salaryThisYear *
|
|
102
|
-
(matchedPct / 100) *
|
|
103
|
-
(employerMatchPercent / 100);
|
|
104
|
-
// End-of-year compounding: prior balance grows, then this year's
|
|
105
|
-
// contributions land. (Matches site `calculateFutureValue` for flat salary.)
|
|
106
|
-
const grownBalance = balance * (1 + r);
|
|
107
|
-
const growthThisYear = grownBalance - balance;
|
|
108
|
-
balance = grownBalance + employeeContrib + employerMatch;
|
|
109
|
-
totalContributions += employeeContrib;
|
|
110
|
-
employerContribTotal += employerMatch;
|
|
111
|
-
rows.push({
|
|
112
|
-
year: i,
|
|
113
|
-
age: ageThisYear,
|
|
114
|
-
employeeContribution: ROUND(employeeContrib),
|
|
115
|
-
employerMatch: ROUND(employerMatch),
|
|
116
|
-
growth: ROUND(growthThisYear),
|
|
117
|
-
endingBalance: ROUND(balance),
|
|
118
|
-
});
|
|
119
|
-
}
|
|
120
|
-
const principalPlusContribs = currentBalance + totalContributions + employerContribTotal;
|
|
121
|
-
const growthEarned = balance - principalPlusContribs;
|
|
122
|
-
return {
|
|
123
|
-
futureBalance: ROUND(balance),
|
|
124
|
-
totalContributions: ROUND(totalContributions),
|
|
125
|
-
employerContribTotal: ROUND(employerContribTotal),
|
|
126
|
-
growthEarned: ROUND(growthEarned),
|
|
127
|
-
yearByYear: rows,
|
|
128
|
-
};
|
|
129
|
-
}
|
|
130
|
-
//# sourceMappingURL=retirement401k.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"retirement401k.js","sourceRoot":"","sources":["../../src/engines/retirement401k.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Social Security estimate engine — lifted from
|
|
3
|
-
* site/src/utils/social-security-engine.js (functions `estimateAIME`,
|
|
4
|
-
* `calculatePIA`, `calculateFRA`, `calculateAdjustedBenefit`,
|
|
5
|
-
* `calculateEarlyReduction`, `calculateDelayedCredit`,
|
|
6
|
-
* `calculateLifetimeBenefits`).
|
|
7
|
-
*
|
|
8
|
-
* Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
|
|
9
|
-
* parity test against the site source as the gate.
|
|
10
|
-
*
|
|
11
|
-
* Math reference (mirrors SSA Publication 05-10035):
|
|
12
|
-
* AIME = (min(salary, ssWageBase) * 0.65 * min(yearsWorked, 35)) / 420
|
|
13
|
-
* (simplified site approximation; exact AIME requires 35-year history)
|
|
14
|
-
* PIA = 0.90 * min(AIME, BP1)
|
|
15
|
-
* + 0.32 * (min(AIME, BP2) - BP1) if AIME > BP1
|
|
16
|
-
* + 0.15 * (AIME - BP2) if AIME > BP2
|
|
17
|
-
* (rounded down to nearest $0.10)
|
|
18
|
-
* benefit_at_claim = PIA * adjustment_factor(claimAge, FRA)
|
|
19
|
-
*
|
|
20
|
-
* Output values are USD monthly benefits (or USD lifetime totals).
|
|
21
|
-
*/
|
|
22
|
-
/**
|
|
23
|
-
* SemVer of the SS engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041 Position #4a):
|
|
24
|
-
* major bump = math change; minor = additive output; patch = numerical correction.
|
|
25
|
-
* NOT bumped for cosmetic refactors.
|
|
26
|
-
* - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
|
|
27
|
-
* - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
|
|
28
|
-
* Math unchanged.
|
|
29
|
-
*/
|
|
30
|
-
export declare const ENGINE_VERSION = "1.0.0";
|
|
31
|
-
/** Inputs to the SS estimate engine. */
|
|
32
|
-
export interface SocialSecurityEstimateInput {
|
|
33
|
-
/** Birth year (1943-2004 supported). */
|
|
34
|
-
birthYear: number;
|
|
35
|
-
/** Current/final annual earnings, USD. */
|
|
36
|
-
currentEarnings: number;
|
|
37
|
-
/** Claiming age (62..70). */
|
|
38
|
-
claimAge: number;
|
|
39
|
-
/**
|
|
40
|
-
* Years of work earning SS credits. Used in the simplified AIME estimate.
|
|
41
|
-
* Defaults to 35 (the SSA averaging window).
|
|
42
|
-
*/
|
|
43
|
-
yearsWorked?: number;
|
|
44
|
-
/** Life-expectancy assumption for lifetime projection. Default 85. */
|
|
45
|
-
lifeExpectancy?: number;
|
|
46
|
-
}
|
|
47
|
-
/** Result payload returned by the engine. */
|
|
48
|
-
export interface SocialSecurityEstimateResult {
|
|
49
|
-
/** Monthly benefit at Full Retirement Age (PIA), USD. */
|
|
50
|
-
monthlyBenefitAtFRA: number;
|
|
51
|
-
/** Monthly benefit at the user's chosen claim age, USD. */
|
|
52
|
-
adjustedMonthlyBenefit: number;
|
|
53
|
-
/** Total benefit collected from claimAge through lifeExpectancy, USD. */
|
|
54
|
-
lifetimeBenefitProjection: number;
|
|
55
|
-
/** Full Retirement Age in decimal (e.g., 67.0 or 66.5). */
|
|
56
|
-
fraAge: number;
|
|
57
|
-
/** Eligibility year used for bend-point lookup (birthYear + 62). */
|
|
58
|
-
eligibilityYear: number;
|
|
59
|
-
/** Whether bend points are estimated (eligibility year beyond published table). */
|
|
60
|
-
bendPointsEstimated: boolean;
|
|
61
|
-
}
|
|
62
|
-
export declare function estimate(input: SocialSecurityEstimateInput): SocialSecurityEstimateResult;
|
|
63
|
-
//# sourceMappingURL=socialSecurity.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"socialSecurity.d.ts","sourceRoot":"","sources":["../../src/engines/socialSecurity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC,wCAAwC;AACxC,MAAM,WAAW,2BAA2B;IAC1C,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,eAAe,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,4BAA4B;IAC3C,yDAAyD;IACzD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,sBAAsB,EAAE,MAAM,CAAC;IAC/B,yEAAyE;IACzE,yBAAyB,EAAE,MAAM,CAAC;IAClC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAsGD,wBAAgB,QAAQ,CACtB,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CAiC9B"}
|
|
@@ -1,139 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Social Security estimate engine — lifted from
|
|
3
|
-
* site/src/utils/social-security-engine.js (functions `estimateAIME`,
|
|
4
|
-
* `calculatePIA`, `calculateFRA`, `calculateAdjustedBenefit`,
|
|
5
|
-
* `calculateEarlyReduction`, `calculateDelayedCredit`,
|
|
6
|
-
* `calculateLifetimeBenefits`).
|
|
7
|
-
*
|
|
8
|
-
* Per ADR-0039 § 5: pure synchronous functions, ENGINE_VERSION constant,
|
|
9
|
-
* parity test against the site source as the gate.
|
|
10
|
-
*
|
|
11
|
-
* Math reference (mirrors SSA Publication 05-10035):
|
|
12
|
-
* AIME = (min(salary, ssWageBase) * 0.65 * min(yearsWorked, 35)) / 420
|
|
13
|
-
* (simplified site approximation; exact AIME requires 35-year history)
|
|
14
|
-
* PIA = 0.90 * min(AIME, BP1)
|
|
15
|
-
* + 0.32 * (min(AIME, BP2) - BP1) if AIME > BP1
|
|
16
|
-
* + 0.15 * (AIME - BP2) if AIME > BP2
|
|
17
|
-
* (rounded down to nearest $0.10)
|
|
18
|
-
* benefit_at_claim = PIA * adjustment_factor(claimAge, FRA)
|
|
19
|
-
*
|
|
20
|
-
* Output values are USD monthly benefits (or USD lifetime totals).
|
|
21
|
-
*/
|
|
22
|
-
import { SSA_BEND_POINTS, SS_WAGE_BASE, DEFAULT_LIFE_EXPECTANCY, } from "./data/ssa.js";
|
|
23
|
-
/**
|
|
24
|
-
* SemVer of the SS engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041 Position #4a):
|
|
25
|
-
* major bump = math change; minor = additive output; patch = numerical correction.
|
|
26
|
-
* NOT bumped for cosmetic refactors.
|
|
27
|
-
* - 0.2.0 (v0.1.0 publish): initial port (S136), shipped under out-of-policy package-surface version.
|
|
28
|
-
* - 1.0.0 (v0.2.0 publish): one-time reset to align with ADR-0039 § 5 per ADR-0041 D4a.
|
|
29
|
-
* Math unchanged.
|
|
30
|
-
*/
|
|
31
|
-
export const ENGINE_VERSION = "1.0.0";
|
|
32
|
-
// ---------------------------------------------------------------------------
|
|
33
|
-
// FRA lookup (mirrors site engine FRA_TABLE)
|
|
34
|
-
// ---------------------------------------------------------------------------
|
|
35
|
-
/** FRA in years.months for a given birth year. Returns total months for math use. */
|
|
36
|
-
function fraTotalMonths(birthYear) {
|
|
37
|
-
if (birthYear <= 1954)
|
|
38
|
-
return 792; // 66.0
|
|
39
|
-
if (birthYear >= 1960)
|
|
40
|
-
return 804; // 67.0
|
|
41
|
-
// 1955-1959 transition: +2 months per year.
|
|
42
|
-
const map = {
|
|
43
|
-
1955: 794,
|
|
44
|
-
1956: 796,
|
|
45
|
-
1957: 798,
|
|
46
|
-
1958: 800,
|
|
47
|
-
1959: 802,
|
|
48
|
-
};
|
|
49
|
-
return map[birthYear] ?? 804;
|
|
50
|
-
}
|
|
51
|
-
function fraDecimal(birthYear) {
|
|
52
|
-
return fraTotalMonths(birthYear) / 12;
|
|
53
|
-
}
|
|
54
|
-
// ---------------------------------------------------------------------------
|
|
55
|
-
// Bend points
|
|
56
|
-
// ---------------------------------------------------------------------------
|
|
57
|
-
function getBendPoints(eligibilityYear) {
|
|
58
|
-
if (SSA_BEND_POINTS[eligibilityYear]) {
|
|
59
|
-
return { ...SSA_BEND_POINTS[eligibilityYear], estimated: false };
|
|
60
|
-
}
|
|
61
|
-
const years = Object.keys(SSA_BEND_POINTS)
|
|
62
|
-
.map(Number)
|
|
63
|
-
.sort((a, b) => b - a);
|
|
64
|
-
const latest = years[0];
|
|
65
|
-
return { ...SSA_BEND_POINTS[latest], estimated: true };
|
|
66
|
-
}
|
|
67
|
-
// ---------------------------------------------------------------------------
|
|
68
|
-
// AIME / PIA / claim-age adjustment (verbatim port of site math)
|
|
69
|
-
// ---------------------------------------------------------------------------
|
|
70
|
-
function estimateAIME(currentSalary, yearsWorked, taxYear) {
|
|
71
|
-
const wageBase = SS_WAGE_BASE[taxYear] ?? SS_WAGE_BASE[2026];
|
|
72
|
-
const cappedSalary = Math.min(currentSalary, wageBase);
|
|
73
|
-
const careerAverageFactor = 0.65;
|
|
74
|
-
const avgAnnualEarnings = cappedSalary * careerAverageFactor;
|
|
75
|
-
const effectiveYears = Math.min(yearsWorked, 35);
|
|
76
|
-
const totalEarnings = avgAnnualEarnings * effectiveYears;
|
|
77
|
-
return Math.floor(totalEarnings / 420);
|
|
78
|
-
}
|
|
79
|
-
function calculatePIA(aime, bp) {
|
|
80
|
-
let pia = 0.9 * Math.min(aime, bp.first);
|
|
81
|
-
if (aime > bp.first) {
|
|
82
|
-
pia += 0.32 * (Math.min(aime, bp.second) - bp.first);
|
|
83
|
-
}
|
|
84
|
-
if (aime > bp.second) {
|
|
85
|
-
pia += 0.15 * (aime - bp.second);
|
|
86
|
-
}
|
|
87
|
-
// PIA rounded down to nearest $0.10 per SSA convention.
|
|
88
|
-
return Math.floor(pia * 10) / 10;
|
|
89
|
-
}
|
|
90
|
-
/**
|
|
91
|
-
* Adjustment factor for claim age vs. FRA. < 1 is early reduction, > 1 is delayed credit.
|
|
92
|
-
* Mirrors site `calculateEarlyReduction` + `calculateDelayedCredit`.
|
|
93
|
-
*/
|
|
94
|
-
function adjustmentFactor(claimAgeMonths, fraMonths) {
|
|
95
|
-
if (claimAgeMonths === fraMonths)
|
|
96
|
-
return 1.0;
|
|
97
|
-
if (claimAgeMonths < fraMonths) {
|
|
98
|
-
const monthsEarly = fraMonths - claimAgeMonths;
|
|
99
|
-
let reduction = 0;
|
|
100
|
-
const first36 = Math.min(monthsEarly, 36);
|
|
101
|
-
reduction += first36 * (5 / 9) / 100;
|
|
102
|
-
if (monthsEarly > 36) {
|
|
103
|
-
reduction += (monthsEarly - 36) * (5 / 12) / 100;
|
|
104
|
-
}
|
|
105
|
-
return Math.max(0, 1 - reduction);
|
|
106
|
-
}
|
|
107
|
-
// Delayed credit: 2/3 of 1% per month (8%/yr), capped at 70 (= 840 months).
|
|
108
|
-
const cappedMonths = Math.min(claimAgeMonths, 840);
|
|
109
|
-
if (cappedMonths <= fraMonths)
|
|
110
|
-
return 1.0;
|
|
111
|
-
const monthsDelayed = cappedMonths - fraMonths;
|
|
112
|
-
return 1 + monthsDelayed * (2 / 3) / 100;
|
|
113
|
-
}
|
|
114
|
-
// ---------------------------------------------------------------------------
|
|
115
|
-
// Public API
|
|
116
|
-
// ---------------------------------------------------------------------------
|
|
117
|
-
export function estimate(input) {
|
|
118
|
-
const { birthYear, currentEarnings, claimAge, yearsWorked = 35, lifeExpectancy = DEFAULT_LIFE_EXPECTANCY, } = input;
|
|
119
|
-
const eligibilityYear = birthYear + 62;
|
|
120
|
-
const bp = getBendPoints(eligibilityYear);
|
|
121
|
-
const aime = estimateAIME(currentEarnings, yearsWorked, eligibilityYear);
|
|
122
|
-
const pia = calculatePIA(aime, bp);
|
|
123
|
-
const fraMonths = fraTotalMonths(birthYear);
|
|
124
|
-
const claimAgeMonths = claimAge * 12;
|
|
125
|
-
const adj = adjustmentFactor(claimAgeMonths, fraMonths);
|
|
126
|
-
const adjustedMonthly = Math.round(pia * adj * 100) / 100;
|
|
127
|
-
// Lifetime: monthly * 12 months * (lifeExpectancy − claimAge) years.
|
|
128
|
-
const yearsReceiving = Math.max(0, lifeExpectancy - claimAge);
|
|
129
|
-
const lifetime = Math.round(adjustedMonthly * 12 * yearsReceiving);
|
|
130
|
-
return {
|
|
131
|
-
monthlyBenefitAtFRA: pia,
|
|
132
|
-
adjustedMonthlyBenefit: adjustedMonthly,
|
|
133
|
-
lifetimeBenefitProjection: lifetime,
|
|
134
|
-
fraAge: fraDecimal(birthYear),
|
|
135
|
-
eligibilityYear,
|
|
136
|
-
bendPointsEstimated: bp.estimated,
|
|
137
|
-
};
|
|
138
|
-
}
|
|
139
|
-
//# sourceMappingURL=socialSecurity.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"socialSecurity.js","sourceRoot":"","sources":["../../src/engines/socialSecurity.ts"],"names":[],"mappings":"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"}
|
package/dist/envelope.d.ts
DELETED
|
@@ -1,76 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Result + Error envelopes per ADR-0039 § 3 and § 4.
|
|
3
|
-
*
|
|
4
|
-
* Every tool returns a `ToolResult<T>` on success or a `ToolError` on failure.
|
|
5
|
-
* The envelope shape is invariant across all tools — only the `result` payload
|
|
6
|
-
* type varies. Provenance (engineVersion, methodology, calculatedAt) is
|
|
7
|
-
* non-negotiable.
|
|
8
|
-
*/
|
|
9
|
-
/**
|
|
10
|
-
* Successful tool result envelope.
|
|
11
|
-
* @template T - Tool-specific payload type (always a structured object, never a bare number).
|
|
12
|
-
*/
|
|
13
|
-
export interface ToolResult<T> {
|
|
14
|
-
/** Tool-specific payload. Structured object. Monetary fields are bare USD numbers. */
|
|
15
|
-
result: T;
|
|
16
|
-
/** Canonical YMYL disclaimer string (single source of truth at packages/mcp/src/disclaimers/ymyl.ts). */
|
|
17
|
-
disclaimer: string;
|
|
18
|
-
/** Methodology pointer with versioned URL. */
|
|
19
|
-
methodology: {
|
|
20
|
-
/** Absolute URL to the methodology .md companion (ADR-0033) or HTML page if no companion. */
|
|
21
|
-
url: string;
|
|
22
|
-
/** ISO date of the methodology document's last-modified front-matter (per ADR-0035). */
|
|
23
|
-
version: string;
|
|
24
|
-
};
|
|
25
|
-
/** ISO-8601 UTC timestamp the tool was invoked. */
|
|
26
|
-
calculatedAt: string;
|
|
27
|
-
/** SemVer of the calc engine module that produced `result`. Bumped when math changes. */
|
|
28
|
-
engineVersion: string;
|
|
29
|
-
}
|
|
30
|
-
/**
|
|
31
|
-
* Error envelope namespaces per ADR-0039 § 4.
|
|
32
|
-
*
|
|
33
|
-
* - INPUT_VALIDATION: Zod or bounds validation failed. Not retriable.
|
|
34
|
-
* - BUSINESS_RULE: Inputs valid but produce an undefined result. Not retriable.
|
|
35
|
-
* - INTERNAL: Unexpected engine error. Not retriable; opaque message to caller.
|
|
36
|
-
* - RATE_LIMIT: Free-tier rate limit hit. Retriable after the window resets.
|
|
37
|
-
*/
|
|
38
|
-
export type ToolErrorCode = "INPUT_VALIDATION" | "BUSINESS_RULE" | "INTERNAL" | "RATE_LIMIT";
|
|
39
|
-
/**
|
|
40
|
-
* Failure envelope returned to the MCP transport with `isError: true`.
|
|
41
|
-
* Tools never throw to the transport — all failures funnel through this shape.
|
|
42
|
-
*/
|
|
43
|
-
export interface ToolError {
|
|
44
|
-
error: {
|
|
45
|
-
/** Stable machine-readable code, namespaced by tool family. */
|
|
46
|
-
code: ToolErrorCode;
|
|
47
|
-
/** Human-readable description (no PII; safe to surface to end-user). */
|
|
48
|
-
message: string;
|
|
49
|
-
/** For validation errors, the input field that failed. */
|
|
50
|
-
field?: string;
|
|
51
|
-
/** True if a retry with same inputs *might* succeed. Validation errors are always false. */
|
|
52
|
-
retriable: boolean;
|
|
53
|
-
};
|
|
54
|
-
}
|
|
55
|
-
/**
|
|
56
|
-
* Build a ToolResult envelope around a successful payload. Helper to keep tools terse.
|
|
57
|
-
*/
|
|
58
|
-
export declare function makeResult<T>(args: {
|
|
59
|
-
result: T;
|
|
60
|
-
methodology: {
|
|
61
|
-
url: string;
|
|
62
|
-
version: string;
|
|
63
|
-
};
|
|
64
|
-
engineVersion: string;
|
|
65
|
-
disclaimer: string;
|
|
66
|
-
}): ToolResult<T>;
|
|
67
|
-
/**
|
|
68
|
-
* Build a ToolError envelope for a failure path. Helper for terse call sites.
|
|
69
|
-
*/
|
|
70
|
-
export declare function makeError(args: {
|
|
71
|
-
code: ToolErrorCode;
|
|
72
|
-
message: string;
|
|
73
|
-
field?: string;
|
|
74
|
-
retriable?: boolean;
|
|
75
|
-
}): ToolError;
|
|
76
|
-
//# sourceMappingURL=envelope.d.ts.map
|
package/dist/envelope.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,sFAAsF;IACtF,MAAM,EAAE,CAAC,CAAC;IACV,yGAAyG;IACzG,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,WAAW,EAAE;QACX,6FAA6F;QAC7F,GAAG,EAAE,MAAM,CAAC;QACZ,wFAAwF;QACxF,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GACrB,kBAAkB,GAClB,eAAe,GACf,UAAU,GACV,YAAY,CAAC;AAEjB;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE;QACL,+DAA+D;QAC/D,IAAI,EAAE,aAAa,CAAC;QACpB,wEAAwE;QACxE,OAAO,EAAE,MAAM,CAAC;QAChB,0DAA0D;QAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,4FAA4F;QAC5F,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE;IAClC,MAAM,EAAE,CAAC,CAAC;IACV,WAAW,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,UAAU,CAAC,CAAC,CAAC,CAQhB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG,SAAS,CASZ"}
|
package/dist/envelope.js
DELETED
|
@@ -1,34 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Result + Error envelopes per ADR-0039 § 3 and § 4.
|
|
3
|
-
*
|
|
4
|
-
* Every tool returns a `ToolResult<T>` on success or a `ToolError` on failure.
|
|
5
|
-
* The envelope shape is invariant across all tools — only the `result` payload
|
|
6
|
-
* type varies. Provenance (engineVersion, methodology, calculatedAt) is
|
|
7
|
-
* non-negotiable.
|
|
8
|
-
*/
|
|
9
|
-
/**
|
|
10
|
-
* Build a ToolResult envelope around a successful payload. Helper to keep tools terse.
|
|
11
|
-
*/
|
|
12
|
-
export function makeResult(args) {
|
|
13
|
-
return {
|
|
14
|
-
result: args.result,
|
|
15
|
-
disclaimer: args.disclaimer,
|
|
16
|
-
methodology: args.methodology,
|
|
17
|
-
calculatedAt: new Date().toISOString(),
|
|
18
|
-
engineVersion: args.engineVersion,
|
|
19
|
-
};
|
|
20
|
-
}
|
|
21
|
-
/**
|
|
22
|
-
* Build a ToolError envelope for a failure path. Helper for terse call sites.
|
|
23
|
-
*/
|
|
24
|
-
export function makeError(args) {
|
|
25
|
-
return {
|
|
26
|
-
error: {
|
|
27
|
-
code: args.code,
|
|
28
|
-
message: args.message,
|
|
29
|
-
field: args.field,
|
|
30
|
-
retriable: args.retriable ?? args.code === "RATE_LIMIT",
|
|
31
|
-
},
|
|
32
|
-
};
|
|
33
|
-
}
|
|
34
|
-
//# sourceMappingURL=envelope.js.map
|
package/dist/envelope.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuDH;;GAEG;AACH,MAAM,UAAU,UAAU,CAAI,IAK7B;IACC,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,YAAY,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtC,aAAa,EAAE,IAAI,CAAC,aAAa;KAClC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,IAKzB;IACC,OAAO;QACL,KAAK,EAAE;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY;SACxD;KACF,CAAC;AACJ,CAAC"}
|