/** * Shared types for `nepali-tax-pro-max`. * * All amounts are NPR rupees (`number`). Internally, sensitive arithmetic * uses paisa-precise rounding. For paisa-precise math callers should pre-round * inputs (e.g. via `Math.round(x * 100) / 100`). */ /** Nepali fiscal year identifier, e.g. `"2081/82"`. */ type FiscalYear = `${number}/${number}`; /** Marital tax filing status. */ type FilingStatus = "single" | "couple"; /** A single income tax slab bracket. */ interface TaxSlab { /** Lower bound (inclusive), in NPR. */ readonly from: number; /** Upper bound (inclusive). `Infinity` for the top bracket. */ readonly to: number; /** Marginal tax rate as a fraction (e.g. `0.10` for 10%). */ readonly rate: number; /** Optional label like `"SST"` for the 1% Social Security Tax slab. */ readonly label?: string; } /** Income tax slab table for one filing status. */ type SlabSet = readonly TaxSlab[]; /** TDS payment categories with their default rates. */ type TdsCategory = "salary" | "rent" | "rent-vehicle" | "service-vat-registered" | "service-non-vat" | "service-non-resident" | "royalty" | "dividend-resident" | "dividend-non-resident" | "interest-bank-individual" | "interest-other" | "commission" | "lottery" | "meeting-allowance" | "aircraft-lease" | "reinsurance-non-resident" | "consumer-committee" | "exam-fee"; /** Capital gains asset categories. */ type CapitalGainsAsset = "shares-listed-individual-short" | "shares-listed-individual-long" | "shares-listed-entity" | "shares-listed-promoter" | "shares-unlisted-individual" | "shares-unlisted-entity" | "land-individual-short" | "land-individual-long" | "land-entity"; /** Corporate tax categories. */ type CorporateCategory = "standard" | "bank-financial" | "insurance" | "telecom" | "petroleum" | "capital-market" | "special-industry" | "export" | "tobacco-alcohol"; /** Annual rate snapshot for a fiscal year. */ interface RatesSnapshot { readonly fiscalYear: FiscalYear; readonly slabsSingle: SlabSet; readonly slabsCouple: SlabSet; readonly tds: Readonly>; readonly vat: { readonly rate: number; readonly thresholdGoods: number; readonly thresholdService: number; }; readonly capitalGains: Readonly>; readonly corporate: Readonly>; readonly ssf: { readonly employee: number; readonly employer: number; readonly breakdown: { readonly medical: number; readonly accident: number; readonly dependent: number; readonly retirement: number; }; }; readonly pf: { readonly employee: number; readonly employer: number; }; readonly deductionCaps: { readonly retirement: number; readonly retirementSsf: number; readonly lifeInsurance: number; readonly healthInsurance: number; readonly donation: number; readonly donationPercentOfTaxableIncome: number; }; readonly sourceUrl?: string; } /** Profile of a tax-paying individual that affects calculations. */ interface TaxProfile { readonly status: FilingStatus; /** Member of Social Security Fund — exempts from 1% SST and unlocks higher retirement cap. */ readonly isSSFMember?: boolean; /** Disabled person — gets +50% on basic exemption. */ readonly isDisabled?: boolean; /** * Female with employment-only income — 10% rebate on tax. * Applies to `status: "single"` only (couples claim deduction differently). */ readonly isWomanRebate?: boolean; /** Pensioner — gets +25% on basic exemption. */ readonly isPensioner?: boolean; /** Remote area category A-E (deduction Rs 10k–50k). */ readonly remoteArea?: "A" | "B" | "C" | "D" | "E"; /** Resident or non-resident — non-resident is flat 25%. */ readonly residency?: "resident" | "non-resident"; } /** Result of an income tax calculation. */ interface IncomeTaxResult { readonly fiscalYear: FiscalYear; readonly grossIncome: number; readonly taxableIncome: number; readonly tax: number; /** Effective rate as a fraction (4 decimal places, e.g. `0.0669` = 6.69%). */ readonly effectiveRate: number; readonly perBracket: ReadonlyArray<{ readonly bracket: TaxSlab; readonly amountInBracket: number; readonly tax: number; }>; readonly notes: readonly string[]; } /** Salary deductions input. */ interface SalaryDeductions { /** Approved retirement contribution (PF/CIT/SSF retirement portion). */ readonly retirement?: number; /** Life insurance premium (capped). */ readonly lifeInsurance?: number; /** Health insurance premium (capped). */ readonly healthInsurance?: number; /** Donation to approved charities (capped). */ readonly donation?: number; } /** Full payroll calculation result. */ interface PayrollResult { readonly fiscalYear: FiscalYear; readonly annualGross: number; readonly annualDeductions: number; readonly taxableIncome: number; readonly annualTax: number; readonly monthlyTds: number; readonly annualNet: number; readonly monthlyNet: number; readonly ssfEmployee: number; readonly ssfEmployer: number; readonly pfEmployee: number; readonly pfEmployer: number; readonly notes: readonly string[]; } /** VAT calculation result. */ interface VatResult { readonly base: number; readonly vat: number; readonly total: number; readonly rate: number; readonly inclusive: boolean; } /** Bill calculation (vendor invoice with VAT + TDS). */ interface BillResult { readonly serviceAmount: number; readonly vat: number; readonly tds: number; readonly grossInvoice: number; readonly payableToVendor: number; readonly payableToGovtVAT: number; readonly payableToGovtTDS: number; } /** * Nepal income tax / TDS / VAT / SSF / PF / capital gains rates for * **Fiscal Year 2081/82** (Shrawan 1, 2081 → Ashad end, 2082 ≈ 2024-07-16 → 2025-07-16). * * Source: Finance Act 2081 (Jestha 15, 2081), IRD circulars, SSF schedule. * * **Verify before deploying for production tax filings.** Rates here reflect * the version published in the gazette as of 2024-07. Any subsequent IRD * notification supersedes — open a PR to add a new FY file rather than * mutating this one. * * Sources: * - https://ird.gov.np (Finance Act 2081) * - https://mof.gov.np (Budget Speech 2081/82) * - https://ssf.gov.np (SSF contribution schedule) */ declare const RATES_FY_2081_82: RatesSnapshot; /** * Fiscal-year rate registry. To add a new FY: * 1. Create `fy-.ts` next to this file with a `RATES_FY_` export. * 2. Add it to the `RATES_BY_FY` map below. * 3. Update `DEFAULT_FISCAL_YEAR` if the new FY is the current one. * * Rates from past FYs are immutable — never mutate a published file. */ /** All FYs currently shipped in the package. */ declare const RATES_BY_FY: ReadonlyMap; /** The default fiscal year used when callers don't pass `fiscalYear`. */ declare const DEFAULT_FISCAL_YEAR: FiscalYear; /** Resolve rates for a given fiscal year, defaulting to the current FY. */ declare function getRates(fiscalYear?: FiscalYear): RatesSnapshot; /** All supported fiscal years in the registry. */ declare function getSupportedFiscalYears(): FiscalYear[]; /** * Nepal income tax calculation per IRD slabs. * * Uses the Finance Act slab table for the requested fiscal year (default * 2081/82). Supports single / couple status, SSF members (skip 1% SST), * non-resident flat 25%, women rebate (10% off tax), disabled/pensioner * exemptions, and remote-area allowances. * * @example * calculateIncomeTax({ income: 1_000_000, status: "single" }); * // { fiscalYear: "2081/82", grossIncome: 1000000, taxableIncome: 1000000, * // tax: 85000, effectiveRate: 0.085, perBracket: [...], notes: [...] } */ /** Pure function: apply a slab table to a taxable income amount. */ declare function applySlabs(taxableIncome: number, slabs: SlabSet): { tax: number; perBracket: IncomeTaxResult["perBracket"]; }; /** Income tax options. */ interface IncomeTaxOptions { /** Annual gross income (NPR rupees). */ readonly income: number; /** Filing status — defaults to `"single"`. */ readonly status?: TaxProfile["status"]; /** Fiscal year — defaults to current. */ readonly fiscalYear?: FiscalYear; /** Tax-payer profile flags. */ readonly profile?: Omit; /** Pre-calculated total deductions to subtract from gross. */ readonly deductions?: number; } /** * Calculate income tax for an individual / sole proprietor. * * Returns the slab-applied tax (after rebates and rounding). For full * payroll-style breakdown including SSF/PF/insurance deductions, use * `calculatePayroll` instead. * * @example * calculateIncomeTax({ income: 800_000, status: "single" }).tax; * // 5000 + 20000 + 20000 = 45000 */ declare function calculateIncomeTax(options: IncomeTaxOptions): IncomeTaxResult; /** Quick helper: get the slab table for a status & FY. */ declare function getSlabs(status?: TaxProfile["status"], fiscalYear?: FiscalYear): SlabSet; /** Effective tax rate (= tax / income) for a given income. */ declare function getEffectiveRate(income: number, status?: TaxProfile["status"], fiscalYear?: FiscalYear): number; /** Marginal rate at a given income level. */ declare function getMarginalRate(income: number, status?: TaxProfile["status"], fiscalYear?: FiscalYear): number; /** * TDS (Tax Deducted at Source) calculation. * * @example * calculateTDS({ amount: 100_000, type: "rent" }); * // { tds: 10000, rate: 0.10, type: "rent", fiscalYear: "2081/82" } * * calculateTDS({ amount: 100_000, type: "service-vat-registered" }); * // { tds: 1500, rate: 0.015, ... } */ /** TDS calculation result. */ interface TdsResult { readonly type: TdsCategory; readonly amount: number; readonly rate: number; readonly tds: number; readonly netToVendor: number; readonly fiscalYear: FiscalYear; } /** Options for `calculateTDS`. */ interface TdsOptions { /** Gross payment amount before TDS deduction. */ readonly amount: number; /** Payment category. */ readonly type: TdsCategory; /** Fiscal year — defaults to current. */ readonly fiscalYear?: FiscalYear; } /** * Compute TDS for a payment by category. Salary TDS uses the slab table — * call `calculateSalaryTDS` for that. */ declare function calculateTDS(options: TdsOptions): TdsResult; /** Get the TDS rate for a category at a given FY. */ declare function getTDSRate(type: TdsCategory, fiscalYear?: FiscalYear): number; /** Salary TDS options. */ interface SalaryTdsOptions { /** Annual gross salary (NPR). */ readonly annualIncome: number; /** Filing status — defaults to `"single"`. */ readonly status?: TaxProfile["status"]; /** Tax-payer profile flags. */ readonly profile?: Omit; /** * Annual deductions to subtract from gross. Either: * - a pre-calculated `number` total, or * - a `SalaryDeductions` block (retirement / lifeInsurance / healthInsurance * / donation) which is internally capped via `totalDeductions`. */ readonly deductions?: number | SalaryDeductions; /** Fiscal year — defaults to current. */ readonly fiscalYear?: FiscalYear; } /** Salary TDS result. */ interface SalaryTdsResult { readonly fiscalYear: FiscalYear; readonly annualTax: number; readonly monthlyTds: number; } /** * Compute monthly salary TDS via the slab table. Splits annual tax into 12 * equal monthly withholdings. * * For festival-bonus / 13-month payroll, use `calculatePayroll` which handles * proration explicitly. */ declare function calculateSalaryTDS(options: SalaryTdsOptions): SalaryTdsResult; /** Convenience: compute total deductions from a `SalaryDeductions` block. */ declare function totalDeductions(d: SalaryDeductions, fiscalYear?: FiscalYear, isSSFMember?: boolean, taxableIncomeBeforeDonation?: number): number; /** * VAT (Value Added Tax) — 13% standard rate on Nepali invoices. * * @example * calculateVAT(1000); // { base: 1000, vat: 130, total: 1130, ... } * calculateVAT(1130, { inclusive: true }); // { base: 1000, vat: 130, total: 1130, ... } * extractVAT(1130); // 130 * isAboveVATThreshold(60_00_000, "goods") // true */ /** Options for `calculateVAT`. */ interface VatOptions { /** Whether the input amount is VAT-inclusive (default `false`). */ readonly inclusive?: boolean; /** Fiscal year (default current). */ readonly fiscalYear?: FiscalYear; /** Override VAT rate (default = current FY rate, 13%). */ readonly rate?: number; } /** * Compute VAT on a base amount. By default treats input as VAT-exclusive. * Pass `{ inclusive: true }` to back-out VAT from a tax-included total. * * @example * calculateVAT(1000) // exclusive: vat=130, total=1130 * calculateVAT(1130, { inclusive: true }) // inclusive: base=1000, vat=130 */ declare function calculateVAT(amount: number, options?: VatOptions): VatResult; /** Just return the VAT amount from an inclusive total. */ declare function extractVAT(totalInclusive: number, fiscalYear?: FiscalYear): number; /** Just return the VAT amount on top of an exclusive base. */ declare function addVAT(base: number, fiscalYear?: FiscalYear): number; /** Get the current standard VAT rate (default 13%). */ declare function getVATRate(fiscalYear?: FiscalYear): number; /** Get the VAT-registration threshold for goods or services. */ declare function getVATThreshold(type: "goods" | "service", fiscalYear?: FiscalYear): number; /** True if a turnover triggers mandatory VAT registration. */ declare function isAboveVATThreshold(turnover: number, type: "goods" | "service", fiscalYear?: FiscalYear): boolean; /** * Capital gains tax for shares (listed/unlisted) and real estate. * * Holding-period thresholds: * - Listed shares (individual): 365 days for long-term * - Land/building (individual): 5 years (1825 days) for long-term * * @example * calculateCapitalGains({ * asset: "shares-listed-individual", * gain: 100000, * holdingDays: 400, * ownerType: "individual", * listed: true, * }); * // { tax: 5000, rate: 0.05, ... } */ /** Options for `calculateCapitalGains` — high-level form. */ interface CapitalGainsOptions { /** Realised gain in NPR. */ readonly gain: number; /** * Asset class. * - `"shares-listed"`: ordinary listed shares (individual: 7.5% short / 5% long, entity: 10%). * - `"shares-listed-promoter"`: promoter shares — flat 10% regardless of holding period. * - `"shares-unlisted"`: unlisted/private shares (10% individual, 15% entity). * - `"land"`: real estate (individual: 7.5% short / 5% long over 5y, entity: 1.5%). * * For **bonus shares**, pass `gain = sellPrice * qty` (cost basis = 0) and * `asset: "shares-listed"` — the rate then follows the holding period. */ readonly asset: "shares-listed" | "shares-listed-promoter" | "shares-unlisted" | "land"; /** Owner type. Ignored for `"shares-listed-promoter"` (always individual flat rate). */ readonly ownerType: "individual" | "entity"; /** Holding period in days (only relevant for individuals on listed shares / land). */ readonly holdingDays?: number; /** Fiscal year (default current). */ readonly fiscalYear?: FiscalYear; } /** Result of capital gains calculation. */ interface CapitalGainsResult { readonly fiscalYear: FiscalYear; readonly asset: CapitalGainsAsset; readonly gain: number; readonly rate: number; readonly tax: number; readonly netProceeds: number; } /** Calculate capital gains tax (high-level form). */ declare function calculateCapitalGains(opts: CapitalGainsOptions): CapitalGainsResult; /** Get the rate for a specific canonical asset key. */ declare function getCapitalGainsRate(asset: CapitalGainsAsset, fiscalYear?: FiscalYear): number; /** * Social Security Fund (SSF), Provident Fund (PF), and Citizen Investment * Trust (CIT) contributions. * * **SSF**: 31% total = 11% employee + 20% employer. Sub-allocation: * medical 3.22%, accident 1.40%, dependent 0.27%, retirement 26.11%. * * **PF**: standard 10% + 10% employer match. * * **CIT**: voluntary, capped per `deductionCaps.retirement(Ssf)`. * * @example * calculateSSF(50000) * // { employee: 5500, employer: 10000, total: 15500, breakdown: {...} } * * calculatePF(50000) * // { employee: 5000, employer: 5000, total: 10000 } */ /** SSF result. */ interface SsfResult { readonly basicSalary: number; readonly employee: number; readonly employer: number; readonly total: number; readonly breakdown: { readonly medical: number; readonly accident: number; readonly dependent: number; readonly retirement: number; }; readonly fiscalYear: FiscalYear; } /** * Calculate SSF contribution on a basic salary amount. * @param basicSalary - Monthly OR annual basic salary, library is unit-agnostic. * Result will be in the same units. */ declare function calculateSSF(basicSalary: number, options?: { fiscalYear?: FiscalYear; }): SsfResult; /** PF result. */ interface PfResult { readonly basicSalary: number; readonly employee: number; readonly employer: number; readonly total: number; readonly fiscalYear: FiscalYear; } /** * Calculate Provident Fund contribution. * @param employeeRateOverride Custom employee rate (default 10%); employer matches. */ declare function calculatePF(basicSalary: number, options?: { fiscalYear?: FiscalYear; employeeRate?: number; employerRate?: number; }): PfResult; /** CIT contribution capped at the retirement deduction limit. */ interface CitResult { readonly contribution: number; readonly cappedContribution: number; readonly cap: number; readonly excess: number; readonly fiscalYear: FiscalYear; } /** * Compute the deductible portion of a CIT contribution. Excess over the cap * is still deposited but not deductible. */ declare function calculateCIT(contribution: number, options?: { fiscalYear?: FiscalYear; isSSFMember?: boolean; }): CitResult; /** * Corporate income tax — single-rate by category. * * Standard companies: 25%. Banks/insurance/telecom/petroleum/capital-market/ * tobacco-alcohol: 30%. Special manufacturing industries: 20%. Export: 20%. * * @example * calculateCorporateTax({ profit: 10_000_000, category: "standard" }); * // { tax: 2500000, rate: 0.25, ... } */ /** Options for corporate tax. */ interface CorporateTaxOptions { /** Net profit before tax (NPR). */ readonly profit: number; /** Industry category. */ readonly category: CorporateCategory; /** Fiscal year (default current). */ readonly fiscalYear?: FiscalYear; } /** Corporate tax result. */ interface CorporateTaxResult { readonly fiscalYear: FiscalYear; readonly category: CorporateCategory; readonly profit: number; readonly rate: number; readonly tax: number; readonly netAfterTax: number; } /** Calculate corporate income tax. */ declare function calculateCorporateTax(opts: CorporateTaxOptions): CorporateTaxResult; /** Get the corporate rate for a category at a given FY. */ declare function getCorporateRate(category: CorporateCategory, fiscalYear?: FiscalYear): number; /** * End-to-end payroll calculator — gross monthly salary → annual tax → monthly * net take-home. * * Pipeline: * 1. Annualize gross (months + festival bonus) * 2. Compute SSF/PF deductions * 3. Add other deductions (insurance, donation, retirement) * 4. Cap deductions per FY rules * 5. Apply slabs to taxable income * 6. Apply rebates (women, etc.) * 7. Annual net = gross − SSF/PF employee − tax * 8. Monthly net = annual net / 12 * * @example * calculatePayroll({ * monthlyBasic: 50_000, * monthlyAllowances: 20_000, * festivalBonus: true, * profile: { status: "single", isSSFMember: true }, * deductions: { lifeInsurance: 30_000 }, * }); */ /** Options for `calculatePayroll`. */ interface PayrollOptions { /** Monthly basic salary (used as base for SSF/PF). */ readonly monthlyBasic: number; /** Monthly non-basic allowances (taxable but not contribution-eligible). */ readonly monthlyAllowances?: number; /** Whether a 1-month festival/Dashain bonus is paid (default true). */ readonly festivalBonus?: boolean; /** Number of months (default 12 — Dashain bonus is added separately). */ readonly months?: number; /** Tax profile. */ readonly profile?: TaxProfile; /** Additional voluntary deductions. */ readonly deductions?: SalaryDeductions; /** Use SSF (subtract employee SSF) or PF (default `"ssf"` if SSF member, else `"pf"`). */ readonly retirementScheme?: "ssf" | "pf" | "none"; /** Override PF employee rate (default 10%). */ readonly pfEmployeeRate?: number; /** Override PF employer rate (default 10%). */ readonly pfEmployerRate?: number; /** Fiscal year (default current). */ readonly fiscalYear?: FiscalYear; } /** * Run a full payroll calculation. Returns the breakdown for one fiscal year. * * Conventions: * - Festival bonus = 1 month basic + allowances, fully taxable. * - Annual gross includes festival bonus. * - Retirement scheme contribution counts as a deduction per `deductionCaps`. * - SSF members are exempt from the 1% SST (handled in income-tax module). */ declare function calculatePayroll(options: PayrollOptions): PayrollResult; /** * Vendor bill / invoice calculator: given a service amount + VAT-flag + TDS * category, computes the full breakdown of payments to vendor and government. * * @example * calculateBill({ * serviceAmount: 100_000, * applyVAT: true, * tdsType: "service-vat-registered", * }); * // { * // serviceAmount: 100000, * // vat: 13000, * // tds: 1500, // 1.5% of service amount (not VAT) * // grossInvoice: 113000, * // payableToVendor: 111500, // gross − TDS * // payableToGovtVAT: 13000, * // payableToGovtTDS: 1500, * // } */ /** Options for `calculateBill`. */ interface BillOptions { /** Service amount before VAT. */ readonly serviceAmount: number; /** Whether VAT applies (default false — vendor not VAT-registered). */ readonly applyVAT?: boolean; /** TDS category (skip if no TDS). */ readonly tdsType?: Exclude; /** Override VAT rate. */ readonly vatRate?: number; /** Fiscal year (default current). */ readonly fiscalYear?: FiscalYear; } /** * Compute the full vendor invoice with VAT + TDS. * * TDS is computed on the **service amount only**, not the VAT (per IRD). * VAT is added to the service amount; TDS is deducted from the gross invoice. */ declare function calculateBill(options: BillOptions): BillResult; export { type BillOptions, type BillResult, type CapitalGainsAsset, type CapitalGainsOptions, type CapitalGainsResult, type CitResult, type CorporateCategory, type CorporateTaxOptions, type CorporateTaxResult, DEFAULT_FISCAL_YEAR, type FilingStatus, type FiscalYear, type IncomeTaxOptions, type IncomeTaxResult, type PayrollOptions, type PayrollResult, type PfResult, RATES_BY_FY, RATES_FY_2081_82, type RatesSnapshot, type SalaryDeductions, type SalaryTdsOptions, type SalaryTdsResult, type SlabSet, type SsfResult, type TaxProfile, type TaxSlab, type TdsCategory, type TdsOptions, type TdsResult, type VatOptions, type VatResult, addVAT, applySlabs, calculateBill, calculateCIT, calculateCapitalGains, calculateCorporateTax, calculateIncomeTax, calculatePF, calculatePayroll, calculateSSF, calculateSalaryTDS, calculateTDS, calculateVAT, extractVAT, getCapitalGainsRate, getCorporateRate, getEffectiveRate, getMarginalRate, getRates, getSlabs, getSupportedFiscalYears, getTDSRate, getVATRate, getVATThreshold, isAboveVATThreshold, totalDeductions };