v3.0.0 — Safer GST workflows and stricter data contracts

hsn-code-package v3.0.0

Version 3.0 makes HSN/GST data safer to consume, strengthens financial input validation, secures spreadsheet exports, and replaces the ineffective GST-rate update automation.

This is a semver-major release because several previously permissive behaviors are now intentionally stricter.

Breaking changes

Immutable canonical datasets

getAllHsn() and getAllSac() now return stable, frozen arrays containing frozen records.

Clone records before modifying them:

const editableCodes = hsn.getAllHsn().map(code => ({ ...code }));

TypeScript declarations now expose canonical HSN, SAC, GST-rate, and metadata values as readonly.

Strict GSTR-1 validation

generateGSTR1Summary() now rejects:

• Missing taxable values or rates
• Numeric strings
• Negative values
• NaN and infinite values
• Invalid isInterState values

Each item must provide a finite, non-negative taxableValue and either gstRate or igstRate.

CSV formula protection

exportToCSV() now protects spreadsheet-formula strings by default.

exportToCSV(data, { preventFormulaInjection: false });

Use the opt-out only for trusted data where preserving formula-like input is intentional. Legitimate signed numeric strings such as -1234.50 remain unchanged.

CLI exit statuses

Invalid identifiers passed to these commands now return exit status 1:

hsn validate <code>
hsn gstin <gstin>

Scripts that inspect the command exit status should account for this corrected behavior.

TypeScript metadata contract

HsnStats now includes these required fields:

gstRatesLastUpdated
gstRateSource
gstNotificationRef

gstRateSource is one of:

'chapter-level' | 'mixed' | 'authoritative-excel'

Security improvements

• Replaced vulnerable legacy spreadsheet parsers with integrity-pinned SheetJS 0.20.3.
• Added spreadsheet-formula injection protection to CSV headers and cells.
• Changed the GST-rate workflow to use read-only repository permissions.
• Removed automatic commits and pushes from the scheduled rate workflow.
• Added strict HTTPS, redirect, content-type, file-signature, size, duplicate, and workbook-overlap validation.

GST-rate workflow changes

The old weekly workflow produced metadata-only commits without materially updating any of the 12,604 bundled rates.

The replacement workflow:

• Runs only when GST_RATE_SOURCE_URL is configured
• Never modifies repository files
• Fails closed when downloading or parsing fails
• Requires at least 80% of workbook rows to match bundled HSN codes
• Opens a review issue when validated rate content differs
• Reports mixed provenance whenever chapter-level fallbacks remain
• Reports authoritative-excel only when every generated rate comes from the workbook

Local updates remain an explicit reviewed operation:

node scripts/update-gst-rates.js --write

Correctness fixes

• Invoice totals now support downward round-off adjustments.
• Signed cent rounding is symmetric and no longer exposes negative zero.
• GSTR-1 summaries reject malformed financial data instead of silently converting it to zero.
• CLI validation failures now return reliable nonzero statuses.
• GST rates and metadata are staged together before either target is replaced.
• Cached public datasets can no longer be corrupted through consumer mutation.

Tooling and quality

• Strict TypeScript checking is now required by CI.
• Publishing is blocked when tests or TypeScript checks fail.
• Expanded regression coverage to 208 passing tests.
• Verified the final npm package contains only the expected runtime files.
• Production dependency audit reports zero vulnerabilities.

Upgrade

npm install hsn-code-package@3

Review the migration guidance in the README before upgrading applications that mutate returned records, accept loosely typed GSTR-1 input, depend on exact CSV output, or inspect CLI exit statuses.