Skip to content

v2.3.0 — Full GST Toolkit

Choose a tag to compare

View all tags
@karthi-21 karthi-21 released this 03 Jun 02:25
· 27 commits to main since this release
v2.3.0
f843f57
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

What's new in v2.3.0

This release transforms hsn-code-package from an HSN lookup library into a complete, zero-runtime-dependency GST toolkit for India.

GST rate data (Issue #2)

  • Bundled IGST/CGST/SGST/cess rates for all 12,604 HSN codes — derived from CBIC Notification No. 09/2025-CT(Rate) (effective 22 Sep 2025)
  • New: getGstRateByCode(code), getHsnByExactCodeWithRate(code), getHsnByRateSlabs(igstRate)
  • Weekly auto-update GitHub Actions workflow (update-gst-rates.yml) — auto-opens an issue if the update fails
  • npm run update:rates to trigger manually

GST calculation utilities (Issue #3)

  • Pure, rate-agnostic helpers — no HSN data required, pass the rate in
  • calculateTax, calculateGSTBreakdown (CGST/SGST or IGST + cess), reverseCalculateTax
  • getApplicableTaxType (state-code based IGST vs CGST+SGST)
  • calculateInvoiceTotals (multi-line invoice with round-off), groupItemsByTaxRate (GSTR-1 grouping)
  • applyRoundOffRules (half-up 2-decimal rounding)

GSTIN & PAN validation (Issue #4)

  • MOD-36 checksum verification, full 38-state code map
  • validateGSTIN, formatGSTIN, getStateFromGSTIN, isValidPAN, getGSTINComponents

SAC codes for services (Issue #4)

  • 496 real Indian GST SAC codes
  • getAllSac, getSacByCode, searchSac (with matchType + pagination), getCodeDetails (unified HSN/SAC lookup)

Export utilities (Issue #4)

  • exportToCSV (RFC-compliant escaping, custom delimiter/headers)
  • exportToJSON, generateGSTR1Summary (rate-wise CGST/SGST/IGST/cess breakdown)

Advanced HSN lookups (Issue #4)

  • getChapterSummary(chapter) — code count, range, full list
  • findCodesByDescription(keywords) — AND keyword match
  • bulkValidateHsnCodes(codes) — validate an array at once

CLI (hsn)

hsn search "cotton" --limit 10
hsn validate 52010011
hsn chapter 52
hsn gstin 27AAPFU0939F1ZV
hsn sac "construction"
hsn export "silk" --format csv
hsn stats

TypeScript

Complete, audited type definitions bundled — no @types package needed. New npm run typecheck (tsc --strict --noEmit) ensures types stay accurate.

105 tests passing · Node.js >= 14 · Zero runtime dependencies

Full API docs: [README](https://github.com/karthi-21/HSN-Code-Package#readme)

Assets 2
Loading