v2.3.1 — Author, Live Demo & npm fix

v2.3.1

Documentation and metadata update — no API or behaviour changes.

What's new

• Live demo — hsn-gst-demo.karthi-21.com is now
  linked prominently in the README and set as the package homepage on npm. Try every feature
  in the browser without installing anything.

• Author — karthi-21.com added as author URL in package.json
  and credited in the TypeScript definitions (@author + @see tags, visible in IDE tooltips).

Fixes

• Version bump from 2.3.0 to 2.3.1 to resolve npm 403 conflict from a double-publish attempt.

---

No code changes. Safe to upgrade from any 2.x version.

Full API docs & live demo: hsn-gst-demo.karthi-21.com

v2.3.0 — Full GST Toolkit

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)

v2.0.0 — Zero-dependency rewrite with new lookup APIs and TypeScript support

What's new in v2.0.0

🐛 Critical bug fixes

• Exports were completely broken — module.exports used bitwise OR on functions (evaluates to 0), meaning nothing was exported and the package silently failed for all users. Fixed.
• File path broke outside the package directory — the Excel file was loaded with a relative path, crashing when called from any other directory. Fixed with __dirname.
• Crashes on null/undefined input — getCodeByTxt(null) and getDesByCode(undefined) threw unhandled TypeErrors. Now throws a clear, descriptive error.

⚡ Zero runtime dependencies (was 41)

The package previously installed 41 transitive packages at runtime just to parse one static Excel file. The HSN data is now pre-built into data/hsn_codes.json and shipped directly — no parsing at startup, no extra installs for your users.

🆕 New API methods

Method	Description
getHsnByExactCode(code)	Exact match — returns the single entry or undefined
isValidHsnCode(code)	Boolean validation, safe on null/undefined
getHsnChapter(chapter)	All codes under a 2-digit chapter (e.g. '52' for cotton)
searchHsn(query, options)	Search with matchType, limit, and offset for pagination
getStats()	Dataset metadata — version, date, total codes, chapters

🔷 TypeScript support

Full index.d.ts type definitions included. No @types/ package needed.

✅ Tests

35 tests added with 98% coverage across all functions and edge cases.

📦 Dataset

12,604 HSN codes across 86 chapters (CBIC / WCO Harmonized System Nomenclature).

---

Migration from v1

Existing calls to getAllHsn(), getCodeByTxt(), and getDesByCode() work the same — they now validate input and won't crash on null. Destructured imports are required:

// v1 (broken — nothing was exported)
const hsn = require('hsn-code-package');

// v2 (correct)
const { getAllHsn, getCodeByTxt, getDesByCode } = require('hsn-code-package');