ngtaxkit 0.0.1__tar.gz

ngtaxkit-0.0.1/.gitignore

@@ -0,0 +1,42 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+.turbo/
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+build/
+*.whl
+.hypothesis/
+.pytest_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Coverage
+coverage/
+.nyc_output/
+htmlcov/
+
+# Logs
+*.log
+npm-debug.log*

ngtaxkit-0.0.1/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: ngtaxkit
+Version: 0.0.1
+Summary: Nigerian tax compliance SDK — VAT, PAYE, WHT, Pension, Payroll, Invoicing. NTA 2025 compliant.
+Project-URL: Homepage, https://ngtaxkit.dev
+Project-URL: Repository, https://github.com/mr-tanta/ngtaxkit
+Project-URL: Issues, https://github.com/mr-tanta/ngtaxkit/issues
+Project-URL: Changelog, https://github.com/mr-tanta/ngtaxkit/blob/main/CHANGELOG.md
+Author-email: Abraham Tanta <sir.tanta@gmail.com>
+License-Expression: MIT
+Keywords: compliance,fintech,nigeria,nta-2025,paye,payroll,pension,tax,vat,wht
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: cloud
+Requires-Dist: httpx>=0.27; extra == 'cloud'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: pdf
+Requires-Dist: fpdf2>=2.7; extra == 'pdf'

ngtaxkit-0.0.1/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@ngtaxkit/python",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Python port of ngtaxkit — managed via Turborepo",
+  "scripts": {
+    "build": "echo 'Python build handled by hatchling'",
+    "test": "pytest",
+    "lint": "ruff check src/",
+    "type-check": "mypy --strict src/",
+    "clean": "rm -rf dist build *.egg-info"
+  }
+}

ngtaxkit-0.0.1/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ngtaxkit"
+version = "0.0.1"
+description = "Nigerian tax compliance SDK — VAT, PAYE, WHT, Pension, Payroll, Invoicing. NTA 2025 compliant."
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "Abraham Tanta", email = "sir.tanta@gmail.com" },
+]
+keywords = ["nigeria", "tax", "vat", "paye", "wht", "payroll", "pension", "compliance", "nta-2025", "fintech"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+cloud = ["httpx>=0.27"]
+pdf = ["fpdf2>=2.7"]
+dev = ["pytest>=8.0", "hypothesis>=6.0"]
+
+[project.urls]
+Homepage = "https://ngtaxkit.dev"
+Repository = "https://github.com/mr-tanta/ngtaxkit"
+Issues = "https://github.com/mr-tanta/ngtaxkit/issues"
+Changelog = "https://github.com/mr-tanta/ngtaxkit/blob/main/CHANGELOG.md"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ngtaxkit"]

ngtaxkit-0.0.1/src/ngtaxkit/__init__.py

@@ -0,0 +1,17 @@
+"""ngtaxkit — Nigerian tax compliance SDK (Python port)."""
+
+from . import errors, marketplace, paye, payroll, pension, rates, statutory, types, utils, vat, wht
+
+__all__ = [
+    "errors",
+    "marketplace",
+    "paye",
+    "payroll",
+    "pension",
+    "rates",
+    "statutory",
+    "types",
+    "utils",
+    "vat",
+    "wht",
+]

ngtaxkit-0.0.1/src/ngtaxkit/errors.py

@@ -0,0 +1,158 @@
+"""Error system for ngtaxkit — structured, typed errors with legal citations."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+# ─── Error Codes ──────────────────────────────────────────────────────────────
+
+INVALID_AMOUNT = "NGTK_INVALID_AMOUNT"
+INVALID_CATEGORY = "NGTK_INVALID_CATEGORY"
+INVALID_SERVICE_TYPE = "NGTK_INVALID_SERVICE_TYPE"
+INVALID_STATE = "NGTK_INVALID_STATE"
+INVALID_PENSION_RATE = "NGTK_INVALID_PENSION_RATE"
+INVALID_TIN = "NGTK_INVALID_TIN"
+INVALID_DATE = "NGTK_INVALID_DATE"
+RATE_NOT_FOUND = "NGTK_RATE_NOT_FOUND"
+VALIDATION_ERROR = "NGTK_VALIDATION_ERROR"
+
+
+# ─── Base Error ───────────────────────────────────────────────────────────────
+
+
+class NgtaxkitError(Exception):
+    """Base error class for all ngtaxkit errors."""
+
+    def __init__(self, code: str, message: str, legal_basis: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.legal_basis = legal_basis
+
+    def to_json(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "name": type(self).__name__,
+            "code": self.code,
+            "message": str(self),
+        }
+        if self.legal_basis is not None:
+            result["legal_basis"] = self.legal_basis
+        return result
+
+    def __str__(self) -> str:
+        return super().__str__()
+
+
+# ─── Subclasses ───────────────────────────────────────────────────────────────
+
+
+class InvalidAmountError(NgtaxkitError, ValueError):
+    """Thrown when a monetary amount is invalid (e.g. negative)."""
+
+    def __init__(self, message: str, legal_basis: str | None = None) -> None:
+        NgtaxkitError.__init__(self, INVALID_AMOUNT, message, legal_basis)
+
+
+class InvalidCategoryError(NgtaxkitError, ValueError):
+    """Thrown when an unrecognised VAT category is provided."""
+
+    def __init__(
+        self,
+        message: str,
+        valid_categories: list[str],
+        legal_basis: str | None = None,
+    ) -> None:
+        NgtaxkitError.__init__(self, INVALID_CATEGORY, message, legal_basis)
+        self.valid_categories = valid_categories
+
+    def to_json(self) -> dict[str, Any]:
+        result = super().to_json()
+        result["valid_categories"] = self.valid_categories
+        return result
+
+
+class InvalidServiceTypeError(NgtaxkitError, ValueError):
+    """Thrown when an unrecognised WHT service type is provided."""
+
+    def __init__(
+        self,
+        message: str,
+        valid_service_types: list[str],
+        legal_basis: str | None = None,
+    ) -> None:
+        NgtaxkitError.__init__(self, INVALID_SERVICE_TYPE, message, legal_basis)
+        self.valid_service_types = valid_service_types
+
+    def to_json(self) -> dict[str, Any]:
+        result = super().to_json()
+        result["valid_service_types"] = self.valid_service_types
+        return result
+
+
+class InvalidStateError(NgtaxkitError, ValueError):
+    """Thrown when an invalid Nigerian state code is provided."""
+
+    def __init__(
+        self,
+        message: str,
+        valid_states: list[str],
+        legal_basis: str | None = None,
+    ) -> None:
+        NgtaxkitError.__init__(self, INVALID_STATE, message, legal_basis)
+        self.valid_states = valid_states
+
+    def to_json(self) -> dict[str, Any]:
+        result = super().to_json()
+        result["valid_states"] = self.valid_states
+        return result
+
+
+class InvalidPensionRateError(NgtaxkitError, ValueError):
+    """Thrown when a pension contribution rate is below the legal minimum."""
+
+    def __init__(self, message: str, legal_basis: str | None = None) -> None:
+        NgtaxkitError.__init__(self, INVALID_PENSION_RATE, message, legal_basis)
+
+
+class InvalidTinError(NgtaxkitError, ValueError):
+    """Thrown when a TIN is malformed or invalid."""
+
+    def __init__(self, message: str, legal_basis: str | None = None) -> None:
+        NgtaxkitError.__init__(self, INVALID_TIN, message, legal_basis)
+
+
+class InvalidDateError(NgtaxkitError, ValueError):
+    """Thrown when a date string is invalid or out of range."""
+
+    def __init__(self, message: str, legal_basis: str | None = None) -> None:
+        NgtaxkitError.__init__(self, INVALID_DATE, message, legal_basis)
+
+
+class RateNotFoundError(NgtaxkitError, KeyError):
+    """Thrown when a rate lookup fails (key not found in the registry)."""
+
+    def __init__(self, message: str, legal_basis: str | None = None) -> None:
+        NgtaxkitError.__init__(self, RATE_NOT_FOUND, message, legal_basis)
+
+    def __str__(self) -> str:
+        # KeyError wraps the message in quotes; override to match NgtaxkitError
+        return Exception.__str__(self)
+
+
+class ValidationError(NgtaxkitError, ValueError):
+    """Thrown when one or more field-level validation errors occur."""
+
+    def __init__(
+        self,
+        message: str,
+        errors: list[dict[str, str]],
+        legal_basis: str | None = None,
+    ) -> None:
+        NgtaxkitError.__init__(self, VALIDATION_ERROR, message, legal_basis)
+        self.errors = errors
+
+    def to_json(self) -> dict[str, Any]:
+        result = super().to_json()
+        result["errors"] = self.errors
+        return result

ngtaxkit-0.0.1/src/ngtaxkit/marketplace.py

@@ -0,0 +1,90 @@
+"""Marketplace Module — Pure-function marketplace transaction calculator."""
+
+from __future__ import annotations
+
+from . import vat as vat_module
+from . import wht as wht_module
+from .types import (
+    CommissionBreakdown,
+    MarketplaceResult,
+    TransactionBreakdown,
+    VatLiability,
+)
+from .utils import bankers_round
+
+
+def calculate_transaction(
+    sale_amount: float,
+    platform_commission: float,
+    seller_vat_registered: bool,
+    buyer_type: str = "individual",
+    service_category: str = "standard",
+    seller_tin: str | None = None,
+    platform_is_vat_agent: bool = False,
+    payment_date: str | None = None,
+) -> MarketplaceResult:
+    """Calculate the full tax breakdown for a marketplace buyer-seller transaction.
+
+    1. VAT is calculated on the full sale_amount (not just commission).
+    2. total_from_buyer = sale_amount + vat_amount.
+    3. commission_amount = bankers_round(sale_amount × platform_commission).
+    4. If seller is NOT VAT-registered, WHT is deducted from the seller payout.
+    5. seller_payout = sale_amount − commission_amount − wht_amount.
+    6. Balance invariant: total_from_buyer === seller_payout + commission + VAT + WHT
+    """
+    # 1. Calculate VAT on the full sale amount
+    vat_result = vat_module.calculate(amount=sale_amount, category=service_category)
+    vat_amount = vat_result["vat"]
+
+    # 2. Total charged to buyer
+    total_from_buyer = vat_result["gross"]
+
+    # 3. Platform commission on the sale amount (pre-VAT)
+    commission_amount = bankers_round(sale_amount * platform_commission)
+
+    # 4. WHT: only when seller is NOT VAT-registered
+    wht_result = None
+    wht_amount = 0.0
+    if not seller_vat_registered:
+        wht_result = wht_module.calculate(
+            amount=sale_amount,
+            service_type="professional",
+            payee_type="individual",
+            payment_date=payment_date,
+        )
+        wht_amount = wht_result["wht_amount"]
+
+    # 5. Seller payout — computed as residual to guarantee the balance invariant
+    seller_payout = bankers_round(total_from_buyer - commission_amount - vat_amount - wht_amount)
+
+    # 6. VAT liability assignment
+    vat_collected_by: str = (
+        "seller" if seller_vat_registered and not platform_is_vat_agent else "platform"
+    )
+
+    return MarketplaceResult(
+        sale_amount=sale_amount,
+        vat=vat_result,
+        total_from_buyer=total_from_buyer,
+        platform_commission=CommissionBreakdown(
+            rate=platform_commission,
+            amount=commission_amount,
+            vat_on_commission=0.0,
+            net_commission=commission_amount,
+        ),
+        seller_payout=seller_payout,
+        wht=wht_result,
+        vat_liability=VatLiability(
+            collected_by=vat_collected_by,  # type: ignore[arg-type]
+            amount=vat_amount,
+            remitted_by=vat_collected_by,  # type: ignore[arg-type]
+        ),
+        breakdown=TransactionBreakdown(
+            sale_amount=sale_amount,
+            vat_amount=vat_amount,
+            commission_amount=commission_amount,
+            wht_amount=wht_amount,
+            seller_payout=seller_payout,
+            total_from_buyer=total_from_buyer,
+        ),
+    )

ngtaxkit-0.0.1/src/ngtaxkit/paye.py

@@ -0,0 +1,231 @@
+"""PAYE Module — Pure-function PAYE calculation engine per NTA 2025."""
+
+from __future__ import annotations
+
+from .errors import InvalidAmountError
+from .rates import get
+from .types import (
+    EmployerCosts,
+    MonthlyDeductions,
+    PayeResult,
+    PensionContributions,
+    ReliefBreakdown,
+    TaxBand,
+)
+from .utils import bankers_round
+
+# ─── Internal Helpers ─────────────────────────────────────────────────────────
+
+
+def _load_brackets() -> list[dict]:
+    """Load PAYE brackets from the rates registry."""
+    bands = get("paye.bands")
+    return [
+        {
+            "lower": b["lower"],
+            "upper": b["upper"],
+            "rate": b["rate"],
+        }
+        for b in bands  # type: ignore[union-attr]
+    ]
+
+
+def _apply_bands(taxable_income: float, brackets: list[dict]) -> list[TaxBand]:
+    """Apply graduated tax bands to taxable income and return per-band breakdown."""
+    result: list[TaxBand] = []
+    for band in brackets:
+        upper = band["upper"] if band["upper"] is not None else float("inf")
+        income_in_band = max(0.0, min(taxable_income, upper) - band["lower"])
+        tax_in_band = bankers_round(income_in_band * band["rate"])
+        result.append(
+            TaxBand(
+                lower=band["lower"],
+                upper=upper,
+                rate=band["rate"],
+                tax_in_band=tax_in_band,
+            )
+        )
+    return result
+
+
+# ─── Public API ───────────────────────────────────────────────────────────────
+
+
+def calculate(
+    gross_annual: float,
+    pension_contributing: bool = False,
+    nhf_contributing: bool = False,
+    rent_paid_annual: float = 0.0,
+    disability_status: bool = False,
+    tax_year: int | None = None,
+) -> PayeResult:
+    """Calculate PAYE for a given gross annual income."""
+    if gross_annual < 0:
+        raise InvalidAmountError(
+            f"Gross annual income must be non-negative, received {gross_annual}"
+        )
+
+    exemption_threshold: float = get("paye.exemptionThreshold")  # type: ignore[assignment]
+    legal_basis: str = get("paye.legalBasis")  # type: ignore[assignment]
+    brackets = _load_brackets()
+
+    # ── Exemption check ──
+    if gross_annual <= exemption_threshold:
+        gross_monthly = bankers_round(gross_annual / 12)
+        return PayeResult(
+            gross_annual=gross_annual,
+            gross_monthly=gross_monthly,
+            pension=PensionContributions(employee=0.0, employer=0.0),
+            nhf=0.0,
+            reliefs=ReliefBreakdown(
+                consolidated_relief=0.0,
+                rent_relief=0.0,
+                pension_relief=0.0,
+                nhf_relief=0.0,
+                total=0.0,
+            ),
+            taxable_income=0.0,
+            tax_bands=_apply_bands(0.0, brackets),
+            annual_paye=0.0,
+            monthly_paye=0.0,
+            effective_rate=0.0,
+            exempt=True,
+            exemption_basis=get("paye.exemptionBasis"),  # type: ignore[arg-type]
+            net_monthly=gross_monthly,
+            monthly_deductions=MonthlyDeductions(paye=0.0, pension=0.0, nhf=0.0, total=0.0),
+            employer_costs=EmployerCosts(pension=0.0, nsitf=0.0, itf=0.0, total=0.0),
+            legal_basis=legal_basis,
+        )
+
+    # ── Reliefs ──
+    reliefs = calculate_relief(
+        gross_annual=gross_annual,
+        pension_contributing=pension_contributing,
+        nhf_contributing=nhf_contributing,
+        rent_paid_annual=rent_paid_annual,
+    )
+
+    # ── Taxable income ──
+    taxable_income = bankers_round(max(0.0, gross_annual - reliefs["total"]))
+
+    # ── Apply graduated bands ──
+    tax_bands = _apply_bands(taxable_income, brackets)
+    annual_paye = bankers_round(sum(b["tax_in_band"] for b in tax_bands))
+
+    # ── Monthly values ──
+    gross_monthly = bankers_round(gross_annual / 12)
+    monthly_paye = bankers_round(annual_paye / 12)
+
+    # ── Effective rate (4dp) ──
+    effective_rate = round(annual_paye / gross_annual, 4) if gross_annual > 0 else 0.0
+
+    # ── Pension & NHF amounts ──
+    min_employee_rate: float = get("pension.minimumRates.employee")  # type: ignore[assignment]
+    min_employer_rate: float = get("pension.minimumRates.employer")  # type: ignore[assignment]
+    nhf_rate: float = get("statutory.nhf.rate")  # type: ignore[assignment]
+
+    employee_pension = bankers_round(gross_annual * min_employee_rate) if pension_contributing else 0.0
+    employer_pension = bankers_round(gross_annual * min_employer_rate) if pension_contributing else 0.0
+    nhf_amount = bankers_round(gross_annual * nhf_rate) if nhf_contributing else 0.0
+
+    # ── Monthly deductions ──
+    monthly_employee_pension = bankers_round(employee_pension / 12)
+    monthly_nhf = bankers_round(nhf_amount / 12)
+    total_monthly_deductions = bankers_round(monthly_paye + monthly_employee_pension + monthly_nhf)
+    monthly_deductions = MonthlyDeductions(
+        paye=monthly_paye,
+        pension=monthly_employee_pension,
+        nhf=monthly_nhf,
+        total=total_monthly_deductions,
+    )
+
+    # ── Net monthly ──
+    net_monthly = bankers_round(gross_monthly - total_monthly_deductions)
+
+    # ── Employer costs ──
+    monthly_employer_pension = bankers_round(employer_pension / 12)
+    nsitf_rate: float = get("statutory.nsitf.rate")  # type: ignore[assignment]
+    itf_rate: float = get("statutory.itf.rate")  # type: ignore[assignment]
+    monthly_nsitf = bankers_round(gross_monthly * nsitf_rate)
+    monthly_itf = bankers_round(gross_monthly * itf_rate)
+    employer_costs = EmployerCosts(
+        pension=monthly_employer_pension,
+        nsitf=monthly_nsitf,
+        itf=monthly_itf,
+        total=bankers_round(monthly_employer_pension + monthly_nsitf + monthly_itf),
+    )
+
+    return PayeResult(
+        gross_annual=gross_annual,
+        gross_monthly=gross_monthly,
+        pension=PensionContributions(employee=employee_pension, employer=employer_pension),
+        nhf=nhf_amount,
+        reliefs=reliefs,
+        taxable_income=taxable_income,
+        tax_bands=tax_bands,
+        annual_paye=annual_paye,
+        monthly_paye=monthly_paye,
+        effective_rate=effective_rate,
+        exempt=False,
+        exemption_basis=None,
+        net_monthly=net_monthly,
+        monthly_deductions=monthly_deductions,
+        employer_costs=employer_costs,
+        legal_basis=legal_basis,
+    )
+
+
+def is_exempt(gross_annual: float, tax_year: int | None = None) -> bool:
+    """Check if a gross annual income is exempt from PAYE."""
+    threshold: float = get("paye.exemptionThreshold")  # type: ignore[assignment]
+    return gross_annual <= threshold
+
+
+def get_brackets(tax_year: int | None = None) -> list[dict]:
+    """Get the PAYE graduated tax brackets for a given tax year."""
+    return _load_brackets()
+
+
+def calculate_relief(
+    gross_annual: float,
+    pension_contributing: bool = False,
+    nhf_contributing: bool = False,
+    rent_paid_annual: float = 0.0,
+    disability_status: bool = False,
+    tax_year: int | None = None,
+) -> ReliefBreakdown:
+    """Calculate all PAYE reliefs for the given options."""
+    # CRA: max(₦200K, 1% of gross) + 20% of gross
+    cra_fixed: float = get("paye.cra.fixedAmount")  # type: ignore[assignment]
+    cra_percent: float = get("paye.cra.percentOfGross")  # type: ignore[assignment]
+    cra_additional: float = get("paye.cra.additionalPercentOfGross")  # type: ignore[assignment]
+    consolidated_relief = bankers_round(
+        max(cra_fixed, gross_annual * cra_percent) + gross_annual * cra_additional
+    )
+
+    # Pension relief: 8% of gross (if contributing)
+    min_employee_rate: float = get("pension.minimumRates.employee")  # type: ignore[assignment]
+    pension_relief = bankers_round(gross_annual * min_employee_rate) if pension_contributing else 0.0
+
+    # NHF relief: 2.5% of gross (if contributing)
+    nhf_rate: float = get("statutory.nhf.rate")  # type: ignore[assignment]
+    nhf_relief = bankers_round(gross_annual * nhf_rate) if nhf_contributing else 0.0
+
+    # Rent relief: 20% of rent paid, capped at ₦500K
+    rent_relief_rate: float = get("paye.rentRelief.rate")  # type: ignore[assignment]
+    rent_relief_cap: float = get("paye.rentRelief.cap")  # type: ignore[assignment]
+    rent_relief = (
+        bankers_round(min(rent_paid_annual * rent_relief_rate, rent_relief_cap))
+        if rent_paid_annual > 0
+        else 0.0
+    )
+
+    total = bankers_round(consolidated_relief + pension_relief + nhf_relief + rent_relief)
+
+    return ReliefBreakdown(
+        consolidated_relief=consolidated_relief,
+        rent_relief=rent_relief,
+        pension_relief=pension_relief,
+        nhf_relief=nhf_relief,
+        total=total,
+    )