us-tax-advantaged-params 0.1.0

package/dist/types/USTaxAdvantagedParams.d.cts

@@ -0,0 +1,482 @@
+/**
+ * us-tax-advantaged-params
+ *
+ * A dependency-free U.S. tax-advantaged account parameter engine. Retirement
+ * accounts are the coverage today: contribution limits, phase-outs, shared
+ * statutory limits, and Roth conversions. The annual parameter table is generated from
+ * data/retirement-parameters.json; do not edit the generated block manually.
+ *
+ * This package calculates statutory contribution ceilings and federal income
+ * deltas. It deliberately does not calculate investment returns, distributions,
+ * RMDs, plan nondiscrimination testing, state income tax, or actuarially
+ * determined defined-benefit/cash-balance contributions.
+ */
+export declare const PACKAGE_NAME: "us-tax-advantaged-params";
+export declare const ENGINE_VERSION: "0.1.0";
+export type Money = number;
+export type PersonRole = "taxpayer" | "spouse" | "other";
+export type EmployerContributionTaxTreatment = "pretax" | "roth";
+export type ContributionPreference = "account_type" | "pretax_first" | "roth_first";
+export type SimpleEmployerContributionMethod = "match_3_percent" | "nonelective_2_percent" | "custom";
+export declare enum FilingStatus {
+    SINGLE = "single",
+    MARRIED_FILING_JOINTLY = "married_filing_jointly",
+    MARRIED_FILING_SEPARATELY = "married_filing_separately",
+    HEAD_OF_HOUSEHOLD = "head_of_household",
+    QUALIFYING_SURVIVING_SPOUSE = "qualifying_surviving_spouse"
+}
+export declare enum AccountType {
+    TRADITIONAL_IRA = "traditional_ira",
+    ROTH_IRA = "roth_ira",
+    ROLLOVER_IRA = "rollover_ira",
+    PAYROLL_DEDUCTION_IRA = "payroll_deduction_ira",
+    DEEMED_TRADITIONAL_IRA = "deemed_traditional_ira",
+    DEEMED_ROTH_IRA = "deemed_roth_ira",
+    INHERITED_TRADITIONAL_IRA = "inherited_traditional_ira",
+    INHERITED_ROTH_IRA = "inherited_roth_ira",
+    SEP_IRA = "sep_ira",
+    ROTH_SEP_IRA = "roth_sep_ira",
+    SIMPLE_IRA = "simple_ira",
+    ROTH_SIMPLE_IRA = "roth_simple_ira",
+    SARSEP_IRA = "sarsep_ira",
+    TRADITIONAL_401K = "traditional_401k",
+    ROTH_401K = "roth_401k",
+    SOLO_401K = "solo_401k",
+    ROTH_SOLO_401K = "roth_solo_401k",
+    SIMPLE_401K = "simple_401k",
+    ROTH_SIMPLE_401K = "roth_simple_401k",
+    STARTER_401K = "starter_401k",
+    TRADITIONAL_403B = "traditional_403b",
+    ROTH_403B = "roth_403b",
+    SAFE_HARBOR_403B_DEFERRAL_ONLY = "safe_harbor_403b_deferral_only",
+    GOVERNMENTAL_457B = "governmental_457b",
+    ROTH_GOVERNMENTAL_457B = "roth_governmental_457b",
+    NONGOVERNMENTAL_457B = "nongovernmental_457b",
+    SECTION_457F = "section_457f",
+    TRADITIONAL_TSP = "traditional_tsp",
+    ROTH_TSP = "roth_tsp",
+    SECTION_401A = "section_401a",
+    PROFIT_SHARING_PLAN = "profit_sharing_plan",
+    MONEY_PURCHASE_PLAN = "money_purchase_plan",
+    KEOGH_PLAN = "keogh_plan",
+    ESOP = "esop",
+    DEFINED_BENEFIT_PLAN = "defined_benefit_plan",
+    CASH_BALANCE_PLAN = "cash_balance_plan"
+}
+export declare enum ConversionType {
+    IRA_TO_ROTH_IRA = "ira_to_roth_ira",
+    QUALIFIED_PLAN_TO_ROTH_IRA = "qualified_plan_to_roth_ira",
+    IN_PLAN_ROTH_ROLLOVER = "in_plan_roth_rollover"
+}
+export declare enum CalculationStatus {
+    DETERMINATE = "determinate",
+    DETERMINATE_WITH_ASSUMPTIONS = "determinate_with_assumptions",
+    INDETERMINATE = "indeterminate",
+    UNAVAILABLE = "unavailable",
+    INELIGIBLE = "ineligible"
+}
+export declare enum DiagnosticSeverity {
+    INFO = "info",
+    WARNING = "warning",
+    ERROR = "error"
+}
+export interface Diagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    message: string;
+    path?: string;
+    legalReference?: string;
+}
+export interface CompensationInput {
+    /** Compensation eligible to support regular IRA contributions. */
+    iraCompensation?: Money;
+    /** W-2 wages for general plan-compensation defaults. */
+    w2Compensation?: Money;
+    /** Net earnings after the deductible half of self-employment tax. */
+    selfEmploymentNetEarnings?: Money;
+}
+export interface MagiInput {
+    /** Modified AGI used for direct Roth IRA contribution eligibility. */
+    rothIra?: Money;
+    /** Modified AGI used for the traditional IRA deduction phase-out. */
+    traditionalIraDeduction?: Money;
+    /** Pre-conversion MAGI used only for pre-2010 Roth-conversion eligibility. */
+    rothConversion?: Money;
+}
+export interface PersonInput {
+    id: string;
+    role?: PersonRole;
+    birthDate?: string;
+    birthYear?: number;
+    compensation?: CompensationInput;
+    magi?: MagiInput;
+    coveredByEmployerRetirementPlan?: boolean;
+    /** Used by the MFS IRA rules. Defaults to true for MFS. */
+    livedWithSpouseDuringYear?: boolean;
+    /** Prior-year IRC 3121(a) wages, keyed by common-law employer ID. */
+    priorYearFicaWagesByEmployer?: Record<string, Money>;
+    /** Accumulated nondeductible basis in all traditional/SEP/SIMPLE IRAs. */
+    traditionalSepSimpleIraBasis?: Money;
+    /** December 31 value of all traditional/SEP/SIMPLE IRAs. */
+    yearEndTraditionalSepSimpleIraValue?: Money;
+    /** Other current-year distributions included in the Form 8606 denominator. */
+    otherTraditionalSepSimpleIraDistributions?: Money;
+}
+export interface ExistingContributionInput {
+    employeePreTaxDeferral?: Money;
+    employeeRothDeferral?: Money;
+    employeePreTaxCatchUp?: Money;
+    employeeRothCatchUp?: Money;
+    employeeAfterTax?: Money;
+    employerPreTax?: Money;
+    employerRoth?: Money;
+    deductibleIra?: Money;
+    nondeductibleIra?: Money;
+    rothIra?: Money;
+    special403bCatchUp?: Money;
+    special457CatchUp?: Money;
+}
+export interface Special403bCatchUpInput {
+    eligible?: boolean;
+    yearsOfService: number;
+    priorElectiveDeferrals: Money;
+    priorSpecialCatchUpUsed: Money;
+}
+export interface Section457SpecialCatchUpInput {
+    eligible: boolean;
+    /** Total unused regular 457(b) deferrals from prior eligible years. */
+    unusedDeferralsFromPriorYears: Money;
+}
+export interface PlanRulesInput {
+    /** Compensation recognized by this plan. */
+    planCompensation?: Money;
+    /** Compensation recognized by a 457(b) plan. */
+    includibleCompensation457?: Money;
+    /** Shared IRC 415(c) group; use the same ID for plans of one controlled employer. */
+    annualAdditionsGroupId?: string;
+    /** Optional lower employee limit imposed by the plan document. */
+    planDocumentEmployeeDeferralLimit?: Money;
+    /** Optional lower annual-additions limit imposed by the plan document. */
+    planDocumentAnnualAdditionsLimit?: Money;
+    permitsRothContributions?: boolean;
+    permitsRothCatchUp?: boolean;
+    permitsAfterTaxEmployeeContributions?: boolean;
+    permitsInPlanRothRollover?: boolean;
+    contributionPreference?: ContributionPreference;
+    /** Known employer contribution; preferred when supplied. */
+    expectedEmployerContribution?: Money;
+    /** Employer match dollars per employee-deferral dollar, e.g. 0.5. */
+    employerMatchRate?: number;
+    /** Fraction of compensation eligible for the match, e.g. 0.06. */
+    employerMatchCompensationFraction?: number;
+    /** Employer nonelective contribution as a fraction of compensation. */
+    employerNonelectiveRate?: number;
+    employerContributionTaxTreatment?: EmployerContributionTaxTreatment;
+    simpleEmployerContributionMethod?: SimpleEmployerContributionMethod;
+    simpleCustomEmployerContribution?: Money;
+    simpleEnhancedLimitEligible?: boolean;
+    /** Treat compensation as self-employment net earnings for the employer formula. */
+    isSelfEmployedOwner?: boolean;
+    netEarningsFromSelfEmploymentAfterHalfSETax?: Money;
+    special403bCatchUp?: Special403bCatchUpInput;
+    section457SpecialCatchUp?: Section457SpecialCatchUpInput;
+    /** Grandfathered SARSEP established before 1997. */
+    grandfatheredSarsep?: boolean;
+    /** Used to surface the statutory 2024+ additional SIMPLE nonelective amount. */
+    simpleAdditionalNonelectiveContribution?: Money;
+}
+export interface RetirementAccountInput {
+    id: string;
+    ownerId: string;
+    type: AccountType | string;
+    employerId?: string;
+    priority?: number;
+    planRules?: PlanRulesInput;
+    existingContributions?: ExistingContributionInput;
+}
+export interface RothConversionInput {
+    id: string;
+    ownerId: string;
+    type: ConversionType | string;
+    amount: Money;
+    /** Basis in the specific qualified-plan amount being converted. */
+    afterTaxBasisInConvertedAmount?: Money;
+    /** Overrides the person's aggregate IRA basis for a Form 8606 calculation. */
+    aggregateIraBasisOverride?: Money;
+    /** Overrides the person's December 31 aggregate IRA value. */
+    yearEndAggregateIraValueOverride?: Money;
+    /** Pre-2013 in-plan rollovers generally required an otherwise distributable amount. */
+    otherwiseDistributableAmount?: boolean;
+    sourceAccountId?: string;
+}
+export interface RetirementScenarioInput {
+    taxYear: number;
+    filingStatus: FilingStatus | string;
+    persons: PersonInput[];
+    accounts: RetirementAccountInput[];
+    conversions?: RothConversionInput[];
+}
+export interface ContributionComponents {
+    employeePreTaxDeferral: Money;
+    employeeRothDeferral: Money;
+    employeePreTaxCatchUp: Money;
+    employeeRothCatchUp: Money;
+    employeeAfterTax: Money;
+    employerPreTax: Money;
+    employerRoth: Money;
+    deductibleIra: Money;
+    nondeductibleIra: Money;
+    rothIra: Money;
+    special403bCatchUp: Money;
+    special457CatchUp: Money;
+    /** Known regular contribution whose tax classification cannot be resolved. */
+    unclassifiedIra: Money;
+}
+export interface FederalTaxEffects {
+    federalAgiReduction: Money;
+    federalAgiIncrease: Money;
+    federalTaxableIncomeReduction: Money;
+    formW2Box1WageReduction: Money;
+    ficaWageReduction: Money;
+    selfEmployedRetirementDeduction: Money;
+    nondeductibleContribution: Money;
+    afterTaxOrRothContribution: Money;
+    taxableRothConversion: Money;
+    notes: string[];
+}
+export interface SharedLimitUse {
+    id: string;
+    legalLimit: string;
+    limit: Money | null;
+    usedBeforeAccount: Money;
+    usedByAccount: Money;
+    remainingAfterAccount: Money | null;
+}
+export interface AccountCalculationResult {
+    accountId: string;
+    accountType: AccountType;
+    ownerId: string;
+    employerId?: string;
+    status: CalculationStatus;
+    /** Overall legal ceiling if a monetary contribution ceiling can be calculated. */
+    statutoryMaximumAnnualContribution: Money | null;
+    /** Maximum supported by the supplied plan capabilities and formulas. */
+    maximumAnnualContributionBasedOnInputs: Money | null;
+    maximumAdditionalContributionBasedOnInputs: Money | null;
+    existingAnnualContribution: Money;
+    contributionComponents: ContributionComponents;
+    /** Potential IRC 415(c) space that requires unknown plan/employer terms. */
+    planTermDependentCapacity: Money;
+    federalTaxEffects: FederalTaxEffects;
+    sharedLimits: SharedLimitUse[];
+    diagnostics: Diagnostic[];
+}
+export interface ConversionCalculationResult {
+    conversionId: string;
+    conversionType: ConversionType;
+    ownerId: string;
+    status: CalculationStatus;
+    grossConvertedAmount: Money;
+    taxableAmount: Money | null;
+    nontaxableBasisAmount: Money | null;
+    consumesAnnualContributionLimit: false;
+    federalTaxEffects: FederalTaxEffects;
+    diagnostics: Diagnostic[];
+}
+export interface ScenarioTotals {
+    maximumAnnualContributionBasedOnInputs: Money;
+    maximumAdditionalContributionBasedOnInputs: Money;
+    employeePreTaxContribution: Money;
+    employeeRothOrAfterTaxContribution: Money;
+    employerPreTaxContribution: Money;
+    employerRothContribution: Money;
+    deductibleIraContribution: Money;
+    nondeductibleIraContribution: Money;
+    federalAgiReduction: Money;
+    federalAgiIncrease: Money;
+    taxableRothConversions: Money;
+}
+export interface RetirementScenarioResult {
+    package: typeof PACKAGE_NAME;
+    engineVersion: typeof ENGINE_VERSION;
+    taxYear: number;
+    filingStatus: FilingStatus;
+    parameters: YearParameters;
+    accounts: AccountCalculationResult[];
+    conversions: ConversionCalculationResult[];
+    totals: ScenarioTotals;
+    diagnostics: Diagnostic[];
+}
+interface PhaseoutRange {
+    singleOrHeadOfHousehold?: [Money, Money];
+    marriedFilingJointlyOrQualifyingSurvivingSpouse?: [Money, Money];
+    marriedFilingSeparatelyLivingTogether?: [Money, Money];
+    marriedFilingJointly?: [Money, Money];
+}
+export interface YearParameters {
+    year: number;
+    ira: {
+        baseContributionLimit: Money;
+        age50CatchUp: Money;
+        compensationFraction: number;
+        universalEligibility: boolean;
+        nondeductibleContributionAvailable: boolean;
+        spousalIraAvailable: boolean;
+        nonworkingSpouseIndividualLimit: Money | null;
+        oneEarnerHouseholdCombinedLimit: Money | null;
+        traditionalContributionAge70HalfRestriction: boolean;
+        rothAvailable: boolean;
+    };
+    electiveDeferral402g: Money | null;
+    generalAge50CatchUp: Money;
+    age60To63CatchUp: Money | null;
+    rothCatchUpPriorYearFicaWageThreshold: Money | null;
+    annualAdditions415c: Money | null;
+    annualAdditionsCompensationFraction: number | null;
+    annualCompensation401a17: Money | null;
+    sep: {
+        available: boolean;
+        maximumEmployerContributionRate: number;
+        selfEmployedEquivalentRate: number;
+        minimumEligibleCompensation: Money | null;
+        newSarsepMayBeEstablished: boolean;
+        grandfatheredSarsepMayOperate: boolean;
+        rothSepAvailable: boolean;
+    };
+    simple: {
+        available: boolean;
+        salaryReductionLimit: Money | null;
+        generalAge50CatchUp: Money;
+        age60To63CatchUp: Money | null;
+        certainPlanEnhancedSalaryReductionLimit: Money | null;
+        certainPlanAge50CatchUp: Money | null;
+        additionalNonelectiveContributionCap: Money | null;
+    };
+    section457b: {
+        available: boolean;
+        baseDeferralLimit: Money | null;
+        includibleCompensationFraction: number | null;
+        specialLastThreeYearsMaximum: Money | null;
+        governmentalAge50CatchUp: Money;
+        governmentalAge60To63CatchUp: Money | null;
+        designatedRothAvailableForGovernmentalPlans: boolean;
+    };
+    starterDeferralOnly: {
+        available: boolean;
+        baseDeferralLimit: Money | null;
+        age50CatchUp: Money;
+    };
+    availability: Record<string, boolean>;
+    phaseouts: {
+        traditionalIraCovered: PhaseoutRange | null;
+        traditionalIraSpouseCovered: PhaseoutRange | null;
+        rothIra: PhaseoutRange | null;
+    };
+}
+export declare class RetirementParameterError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class UnsupportedTaxYearError extends RetirementParameterError {
+    constructor(year: number, minimum: number, maximum: number);
+}
+export declare function calculateRetirementScenario(input: RetirementScenarioInput): RetirementScenarioResult;
+export declare class PersonBuilder {
+    private readonly value;
+    constructor(id: string);
+    asTaxpayer(): this;
+    asSpouse(): this;
+    role(role: PersonRole): this;
+    bornOn(birthDate: string): this;
+    bornIn(birthYear: number): this;
+    iraCompensation(amount: Money): this;
+    w2Compensation(amount: Money): this;
+    selfEmploymentNetEarnings(amount: Money): this;
+    rothIraMagi(amount: Money): this;
+    traditionalIraDeductionMagi(amount: Money): this;
+    rothConversionMagi(amount: Money): this;
+    coveredByEmployerPlan(covered?: boolean): this;
+    livedWithSpouseDuringYear(livedTogether?: boolean): this;
+    priorYearFicaWages(employerId: string, amount: Money): this;
+    aggregateTraditionalSepSimpleIraBasis(amount: Money): this;
+    yearEndTraditionalSepSimpleIraValue(amount: Money): this;
+    otherTraditionalSepSimpleIraDistributions(amount: Money): this;
+    build(): PersonInput;
+}
+export declare class RetirementAccountBuilder {
+    private readonly value;
+    constructor(id: string, ownerId: string, type: AccountType | string);
+    owner(ownerId: string): this;
+    accountType(type: AccountType | string): this;
+    employer(employerId: string): this;
+    priority(priority: number): this;
+    planCompensation(amount: Money): this;
+    includible457Compensation(amount: Money): this;
+    annualAdditionsGroup(groupId: string): this;
+    planDocumentEmployeeLimit(amount: Money): this;
+    planDocumentAnnualAdditionsLimit(amount: Money): this;
+    permitsRothContributions(permits?: boolean): this;
+    permitsRothCatchUp(permits?: boolean): this;
+    permitsAfterTaxContributions(permits?: boolean): this;
+    permitsInPlanRothRollover(permits?: boolean): this;
+    contributionPreference(preference: ContributionPreference): this;
+    expectedEmployerContribution(amount: Money, taxTreatment?: EmployerContributionTaxTreatment): this;
+    employerMatch(matchRate: number, compensationFraction: number): this;
+    employerNonelective(rateValue: number): this;
+    employerContributionTaxTreatment(treatment: EmployerContributionTaxTreatment): this;
+    simpleEmployerMethod(method: SimpleEmployerContributionMethod, customAmount?: Money): this;
+    simpleEnhancedLimitEligible(eligible?: boolean): this;
+    simpleAdditionalNonelectiveContribution(amount: Money): this;
+    selfEmployedOwner(netEarningsAfterHalfSETax: Money): this;
+    special403bCatchUp(input: Special403bCatchUpInput): this;
+    special457CatchUp(input: Section457SpecialCatchUpInput): this;
+    grandfatheredSarsep(grandfathered?: boolean): this;
+    existing(contributions: ExistingContributionInput): this;
+    build(): RetirementAccountInput;
+}
+export declare class RothConversionBuilder {
+    private readonly value;
+    constructor(id: string, ownerId: string, type: ConversionType | string, amount: Money);
+    afterTaxBasis(amount: Money): this;
+    aggregateIraBasis(amount: Money): this;
+    yearEndAggregateIraValue(amount: Money): this;
+    otherwiseDistributable(eligible?: boolean): this;
+    sourceAccount(accountId: string): this;
+    build(): RothConversionInput;
+}
+export declare class RetirementScenario {
+    private readonly input;
+    constructor(input: RetirementScenarioInput);
+    calculate(): RetirementScenarioResult;
+    toInput(): RetirementScenarioInput;
+}
+export declare class RetirementScenarioBuilder {
+    private readonly value;
+    static forTaxYear(taxYear: number): RetirementScenarioBuilder;
+    constructor(taxYear: number);
+    filingStatus(status: FilingStatus | string): this;
+    addPerson(person: PersonInput | PersonBuilder): this;
+    taxpayer(id: string, configure?: (builder: PersonBuilder) => void): this;
+    spouse(id: string, configure?: (builder: PersonBuilder) => void): this;
+    addAccount(account: RetirementAccountInput | RetirementAccountBuilder): this;
+    account(id: string, ownerId: string, type: AccountType | string, configure?: (builder: RetirementAccountBuilder) => void): this;
+    addConversion(conversion: RothConversionInput | RothConversionBuilder): this;
+    conversion(id: string, ownerId: string, type: ConversionType | string, amount: Money, configure?: (builder: RothConversionBuilder) => void): this;
+    build(): RetirementScenario;
+    calculate(): RetirementScenarioResult;
+    toInput(): RetirementScenarioInput;
+}
+export declare class USTaxAdvantagedParams {
+    static forTaxYear(taxYear: number): RetirementScenarioBuilder;
+    static calculate(input: RetirementScenarioInput): RetirementScenarioResult;
+    static parametersForYear(taxYear: number): YearParameters;
+    static supportedTaxYears(): {
+        minimum: number;
+        maximum: number;
+    };
+    static generatedThroughTaxYear(): number;
+    static normalizeFilingStatus(status: FilingStatus | string): FilingStatus;
+    static normalizeAccountType(type: AccountType | string): AccountType;
+    static sourceMetadata(): Array<Record<string, string>>;
+}
+export default USTaxAdvantagedParams;