JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 446
  • Score
    100M100P100Q0F
  • License MIT

Nigerian tax compliance SDK — VAT, PAYE, WHT, Pension, Payroll, Invoicing. NTA 2025 compliant.

Package Exports

  • ngtaxkit

Readme

ngtaxkit

Nigerian tax compliance SDK for TypeScript and JavaScript. Implements the Nigeria Tax Act (NTA) 2025 — VAT, PAYE, WHT, Pension, Statutory deductions, Marketplace transactions, Payroll, and document generation.

Zero runtime dependencies for calculations. Pure functions. Deterministic output. Works in Node.js, Bun, Deno, browsers, and Cloudflare Workers.

npm version License: MIT

Install

npm install ngtaxkit

Quick Start

import { vat, paye, wht, pension, payroll } from 'ngtaxkit';

// ─── VAT ────────────────────────────────────────────────────────────────────

// Calculate VAT on an amount
const result = vat.calculate({ amount: 100_000 });
// → { net: 100000, vat: 7500, gross: 107500, rate: 0.075, rateType: 'standard', ... }

// Extract VAT from an inclusive amount
const extracted = vat.extract({ amount: 107_500 });
// → { net: 100000, vat: 7500, gross: 107500, ... }

// Zero-rated categories (basic food, medicine, education, exports, etc.)
const food = vat.calculate({ amount: 50_000, category: 'basic-food' });
// → { vat: 0, rate: 0, rateType: 'zero-rated', inputVatRecoverable: true, ... }

// Exempt categories (residential rent, financial services, etc.)
const rent = vat.calculate({ amount: 200_000, category: 'residential-rent' });
// → { vat: 0, rate: 0, rateType: 'exempt', inputVatRecoverable: false, ... }

// ─── PAYE ───────────────────────────────────────────────────────────────────

const payeResult = paye.calculate({
  grossAnnual: 5_000_000,
  pensionContributing: true,
  nhfContributing: true,
  rentPaidAnnual: 600_000,
});
// → {
//     annualPaye: ...,
//     monthlyPaye: ...,
//     effectiveRate: ...,
//     taxBands: [...],       // graduated bracket breakdown
//     reliefs: { consolidatedRelief, pensionRelief, nhfRelief, rentRelief, total },
//     netMonthly: ...,
//     monthlyDeductions: { paye, pension, nhf, total },
//     employerCosts: { pension, nsitf, itf, total },
//     legalBasis: '...',     // NTA 2025 section reference
//   }

// ─── WHT ────────────────────────────────────────────────────────────────────

const whtResult = wht.calculate({
  amount: 500_000,
  payeeType: 'company',
  serviceType: 'professional',
});
// → {
//     whtAmount: 50000,
//     rate: 0.1,
//     netPayment: 450000,
//     creditNoteRequired: true,
//     remittanceDeadline: '2026-05-21',
//     legalBasis: '...',
//   }

// ─── Pension ────────────────────────────────────────────────────────────────

const pensionResult = pension.calculate({
  basicSalary: 300_000,
  housingAllowance: 100_000,
  transportAllowance: 50_000,
});
// → {
//     pensionableEarnings: 450000,
//     employeeContribution: 36000,  // 8% minimum
//     employerContribution: 45000,  // 10% minimum
//     totalContribution: 81000,
//   }

// ─── Payroll (batch) ────────────────────────────────────────────────────────

const batch = payroll.calculateBatch([
  { name: 'Amina', grossAnnual: 4_000_000, stateOfResidence: 'LA', pensionContributing: true },
  { name: 'Chidi', grossAnnual: 8_000_000, stateOfResidence: 'FC', pensionContributing: true },
  { name: 'Bola',  grossAnnual: 2_400_000, stateOfResidence: 'LA', nhfContributing: true },
]);
// → {
//     employees: [...],          // individual PAYE results per employee
//     byState: {
//       LA: { stateName: 'Lagos', irsName: 'LIRS', employeeCount: 2, totalPaye: ..., ... },
//       FC: { stateName: 'FCT', irsName: 'FCT-IRS', employeeCount: 1, ... },
//     },
//     totals: { totalGross, totalPaye, totalPension, totalNhf, employeeCount },
//   }

Document Generation

Generate NTA 2025-compliant documents from calculation results:

import { create, toPDF, toUBL, toFIRSJSON, toCSV } from 'ngtaxkit';

// Create a validated invoice
const invoice = create({
  seller: { name: 'Acme Ltd', tin: '12345678-0001', address: '123 Marina, Lagos' },
  buyer:  { name: 'Buyer Co', tin: '87654321-0001', address: '45 Wuse, Abuja' },
  items: [
    { description: 'Consulting services', quantity: 1, unitPrice: 500_000, category: 'standard' },
    { description: 'Training materials', quantity: 10, unitPrice: 5_000, category: 'educational-books' },
  ],
});

// Generate outputs
const pdf  = toPDF(invoice);        // Buffer (requires pdfkit as optional dep)
const xml  = toUBL(invoice);        // UBL 3.0 XML string (FIRSMBS e-invoicing)
const json = toFIRSJSON(invoice);   // FIRS-compatible JSON
const csv  = toCSV(invoice);        // CSV export

Other document generators:

import { whtCreditNote, formH1, payslip, vatReturn } from 'ngtaxkit';

whtCreditNote.toPDF(whtResult);  // WHT credit note for payee
formH1.toPDF(payrollBatch);      // Annual PAYE filing form per state
payslip.toPDF(employeeResult);   // Employee payslip with all deductions
vatReturn.toPDF(vatData);        // Monthly/quarterly VAT return

Modules

Module Description
vat VAT calculation, extraction, category classification
paye PAYE income tax with NTA 2025 graduated brackets and reliefs
wht Withholding tax by service type and payee type
pension Contributory Pension Scheme — employee/employer splits
statutory NHF, NSITF, ITF statutory deductions
marketplace End-to-end marketplace transaction: VAT + commission + WHT + payout
payroll Batch payroll with per-state aggregation and filing info
rates Versioned rate registry — all rates, brackets, and thresholds

VAT Categories

Category Rate Type Input VAT Recoverable
standard 7.5% Standard Yes
basic-food 0% Zero-rated Yes
medicine 0% Zero-rated Yes
medical-equipment 0% Zero-rated Yes
medical-services 0% Zero-rated Yes
educational-books 0% Zero-rated Yes
tuition 0% Zero-rated Yes
electricity 0% Zero-rated Yes
export-services 0% Zero-rated Yes
humanitarian-goods 0% Zero-rated Yes
residential-rent 0% Exempt No
public-transport 0% Exempt No
financial-services 0% Exempt No
insurance 0% Exempt No

WHT Service Types

Service Type Individual Rate Company Rate
professional 5% 10%
management 5% 10%
technical 5% 10%
consultancy 5% 10%
commission 5% 10%
construction 2.5% 5%
contract 5% 10%
rent 10% 10%
royalty 5% 10%
dividend 10% 10%
interest 10% 10%

Key Design Decisions

  • Banker's rounding — all monetary values use round-half-even to 2 decimal places
  • Legal citations — every result includes a legalBasis string citing the specific NTA 2025 section
  • Versioned rates — rates are bundled as JSON; override at runtime via rates.setCustom() without upgrading
  • Zero runtime dependencies — calculation engine has no external dependencies
  • Dual format — ships as both ESM and CommonJS with full TypeScript declarations

Rate Overrides

import { rates } from 'ngtaxkit';

// Override a specific rate
rates.setCustom({ 'vat.standard.rate': 0.10 });  // hypothetical 10% VAT

// Check current rate version
rates.getVersion();       // '2026.1'
rates.getEffectiveDate(); // '2026-01-01'

// Reset to bundled rates
rates.clearCustom();

License

MIT — see LICENSE

Author

Abraham Tanta