Feature Request: Add GST Tax Rates, UOM, and Enhanced Fields to HSN Data

[karthi-21]

Hi @karthi-21,

First of all, thank you for building and recently updating hsn-code-package (v2.0.0 with data as of 2026-06-01). It’s one of the cleanest, fastest, and most up-to-date HSN lookup libraries available for Node.js/TypeScript right now.

The current API and data structure are excellent for lookups and validation. However, for real-world GST invoicing, billing, ERP, or compliance tools, one major piece is missing — GST tax rates and related metadata.

Proposed Enhancement

Enhance the dataset to include the following fields per HSN entry (where available):

interface HsnEntry {
  code: string;                    // e.g. "52010011"
  description: string;
  
  // === NEW FIELDS ===
  igst?: number;                   // e.g. 5, 12, 18, 28
  cgst?: number;                   // usually igst/2
  sgst?: number;                   // usually igst/2
  cess?: number;                   // e.g. 0, 15, 25 (for specific items)
  
  unit?: string;                   // e.g. "KGS", "NOS", "LTR", "MTR", "PCS"
  
  chapter?: string;                // already partially available
  section?: string;
  effectiveFrom?: string;          // e.g. "2025-04-01"
  isNilRated?: boolean;
  isExempted?: boolean;
  notificationRef?: string;        // e.g. "Notification No. 01/2025"
}

Why This Would Make the Package "Golden"

• Most developers need HSN → Auto Tax Calculation in one place.
• Reduces need for multiple packages or manual mapping.
• Greatly improves usability for:
  • Invoice generation
  • E-invoicing / E-way bill
  • Product catalog management
  • GST return filing tools

Example Data (Desired Output)

{
  "code": "10019910",
  "description": "Wheat and meslin - Wheat - Other",
  "igst": 5,
  "cgst": 2.5,
  "sgst": 2.5,
  "cess": 0,
  "unit": "KGS",
  "chapter": "10",
  "effectiveFrom": "2025-04-01"
}

Another example (higher rate + cess):

{
  "code": "24022090",
  "description": "Cigarettes containing tobacco - Other",
  "igst": 28,
  "cgst": 14,
  "sgst": 14,
  "cess": 25,
  "unit": "NOS",
  "chapter": "24"
}

Implementation Suggestions

1. Keep it optional — Existing users should not be broken. Maybe:

   • Add a new getAllHsnWithRates() or keep rates in a separate rates.json that can be merged.
   • Or add a flag: includeRates: true in config.

2. Build Process — Since you already have a great build script (scripts/build-data.js + code_list.xlsx), you can extend it to merge data from official CBIC rate tables.

3. Data Sources (for reference):

   • Official CBIC GST Rates page: https://cbic-gst.gov.in/gst-goods-services-rates.html
   • There are open scrapers like https://github.com/geongeorge/GST-HSN-Codes-Fetch that already pull rates.

4. Bonus Features (lower priority):

   • SAC codes for services (optional separate dataset)
   • getTaxDetailsByHsn(code) helper function
   • getHsnByRate(rate) reverse lookup

Benefits Summary

• Makes the package a single source of truth for most GST use cases.
• Increases adoption significantly (many projects currently combine 2–3 packages).
• Maintains the current lightweight & zero-dependency nature.

Would you be open to this enhancement? I (and probably many others) would be happy to help test or contribute data/merging logic if needed.

---

Thanks again for the great work!

---

[karthi-21]

Implemented in #6 (branch claude/elegant-dijkstra-a8o8l, commit e17b3a5).

What was implemented

Data pipeline — scripts/update-gst-rates.js

• Attempts to download the CBIC GST rate Excel from the GST portal and parse it with xlsx.
• Falls back to chapter-level rate mappings from CBIC Notification No. 09/2025-CT(Rate) (effective 22 Sep 2025) when the download fails (the portal returns 403 to non-browser clients, as expected).
• Generates data/gst_rates.json (12,604 entries, one per HSN code) and updates data/metadata.json with gstRatesLastUpdated + gstNotificationRef.
• Handles the chapter-71 special case (precious metals/gems 7101–7114 and imitation jewellery 7117 → 3%).
• Each entry carries igstRate, cgstRate, sgstRate, cessRate, rateSource (chapter-level / cbic-excel), effectiveFrom, notificationRef.

New API (index.js, exported + typed in index.d.ts)

• getGstRateByCode(code) — exact-code rate lookup, returns null if absent.
• getHsnByExactCodeWithRate(code) — HSN entry merged with rate, undefined if code unknown.
• getHsnByRateSlabs(igstRate) — all HSN codes under a given IGST slab.
• Added GstRate and HsnCodeWithRate TypeScript interfaces.

Automation — .github/workflows/update-gst-rates.yml

• Weekly Monday 08:00 UTC cron + manual workflow_dispatch (with force_update), commits changes via a bot account, and opens a GitHub issue automatically on failure.

Other

• tests/gst-rates.test.js added; full suite 85/85 passing.
• Version bumped to 2.3.0; README documents the new GST rate section.

Closes #2.

---

Generated by Claude Code