API Reference

interface SimulateDependentWorkerOptions {
  year: number;
  income: number;
  married?: boolean;
  disabled?: boolean;
  partnerDisabled?: boolean;
  location?: LocationT;
  numberOfHolders?: number | null;
  numberOfDependents?: number | null;
  numberOfDependentsDisabled?: number | null;
  socialSecurityContributionRate?: number;
  twelfths?: Twelfths;
  lunchAllowanceDailyValue?: number;
  lunchAllowanceMode?: "cupon" | "salary";
  lunchAllowanceDaysCount?: number;
  includeLunchAllowanceInJune?: boolean;
  oneHalfMonthTwelfthsLumpSumMonth?: "june" | "december";
  isencaoHorarioMonthly?: number;
  benefitsOfYouthIrs?: boolean;
  yearOfYouthIrs?: number;
}

interface DependentWorkerResult {
  yearly: YearlyDependentWorkerSummary;
  socialSecurityContributionRate: number;
  monthlyBreakdown: MonthlyBreakdownResult[];
}
 
interface YearlyDependentWorkerSummary {
  totalGrossIncomeAmount: number;         // Total gross income for the year
  totalNetIncomeAmount: number;           // Total net income for the year
  totalLunchAllowanceGrossAmount: number; // Total gross lunch allowance for the year
}
 
interface MonthlyBreakdownResult {
  month: MonthName;
  period: PeriodT;
  taxableIncomeForIrsCalculation: number;
  incomeSubjectToIrsAndSocialSecurity: number;
  grossIncome: GrossIncomeAmountBreakdown;
  irsWithholdingTax: IncomeComponentAmountBreakdown;
  socialSecurityContribution: IncomeComponentAmountBreakdown;
  netIncome: IncomeComponentAmountBreakdown;
  lunchAllowance: LunchAllowanceAmountBreakdown;
  subsidyTwelfths: SubsidyTwelfthsAmountBreakdown;
  bracket: BracketResult;
  taxRetentionTable: TaxRetentionTableResult;
  youthIrs: YouthIrsBreakdown;
}
 
interface YouthIrsBreakdown {
  applied: boolean;            // true when IRS Jovem reduces this month's retention
  yearOfBenefit: number;       // resolved year of benefit (1–10)
  exemptionPercentage: number; // 0–1, e.g. 0.75 for 2.º–4.º year in 2025+
  monthlyExemptCap: number;    // (multiplier × IAS) / 14 in euros
  exemptIncome: number;        // amount exempted this month, after the cap
}

type LocationT = "continent" | "azores" | "madeira";

enum Twelfths {
  NONE = 0,           // No holiday allowances
  ONE_HALF_MONTH = 0.5, // 1x50% - One allowance at 50% (half month)
  ONE_MONTH = 1,       // 2x50% - Two allowances at 50% each (one month total)
  TWO_MONTHS = 2       // 2x100% - Two allowances at 100% each (two months total)
}

interface GrossIncomeAmountBreakdown {
  baseSalaryAmount: number;
  baseSalaryAndLunchAllowanceAmount: number;
  totalWithLunchAllowanceAndSubsidyTwelfthsAmount: number;
}

interface IncomeComponentAmountBreakdown {
  totalAmount: number;
  fromBaseSalaryAmount: number;
  fromLunchAllowanceAmount: number;
  fromSubsidyTwelfthsAmount: number;
}

interface LunchAllowanceAmountBreakdown {
  grossAmount: number;
  taxableAmount: number;
  taxExemptAmount: number;
  isPaidInThisMonth: boolean;
}

interface SubsidyTwelfthsAmountBreakdown {
  distributedMonthlyAmount: number; // Monthly distributed portion
  lumpSumAmount: number;            // Lump-sum payment in June/December
  totalAmount: number;              // distributedMonthlyAmount + lumpSumAmount
}

type SituationCodesT =
  | "TABLE1_SINGLE_OR_MARRIED_2_HOLDERS"      // Single or married with 2 holders
  | "TABLE2_SINGLE_ONE_OR_MORE_DEPENDENTS"     // Single with dependents
  | "TABLE3_MARRIED_1_HOLDER"                    // Married, single holder
  | "TABLE4_SINGLE_OR_MARRIED_2_HOLDERS_NO_DEPENDENTS_PERSON_WITH_DISABILITY"  // Single or married 2 holders + disability
  | "TABLE5_SINGLE_ONE_OR_MORE_DEPENDENTS_PERSON_WITH_DISABILITY"     // Single with dependents + disability
  | "TABLE6_MARRIED_2_HOLDERS_ONE_OR_MORE_DEPENDENTS_PERSON_WITH_DISABILITY"    // Married 2 holders with dependents + disability
  | "TABLE7_MARRIED_1_HOLDER_PERSON_WITH_DISABILITY";    // Married single holder + disability

interface Situation {
  code: SituationCodesT;
  description: string;
  conditions: Condition[];
}

interface Condition {
  married: boolean;
  dependents: boolean;
  disabled: boolean;
  partnerDisabled: boolean;
  description: string;
  numberOfHolders?: number | null;
}

interface BracketResult {
  signal: "max" | "min";
  limit: number;
  max_marginal_rate: number;
  deduction: number;
  var1_deduction: number;
  var2_deduction: number;
  dependent_aditional_deduction: number;
  effective_mensal_rate: number;
}

interface TaxRetentionTableResult {
  situation: string;
  description: string;
  brackets: BracketResult[];
  dependent_disabled_addition_deduction?: number;
}

SituationUtils.getSituation(
  married: boolean,
  disabled: boolean,
  partnerDisabled: boolean,
  numberOfHolders?: number | null,
  numberOfDependents?: number
): Situation | undefined

SituationUtils.getSituationFromCode(code: string): Situation | undefined