gst-validator 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Documented package metadata and release baseline.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Vijay Misal
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Vijay Misal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,57 +1,62 @@
-# gst-validator
-
-Validate and parse Indian GSTIN numbers - real checksum verification, state-code lookup, and the embedded PAN, all offline.
-
-## Install
-
-```bash
-npm install gst-validator
-```
-
-## Usage
-
-```js
-import { isValidGstin, parseGstin } from 'gst-validator';
-
-isValidGstin('27AAAPL1234C1ZE'); // true
-isValidGstin('not-a-gstin');     // false
-
-parseGstin('27AAAPL1234C1ZE');
-// {
-//   valid: true,
-//   gstin: '27AAAPL1234C1ZE',
-//   stateCode: '27',
-//   stateName: 'Maharashtra',
-//   pan: 'AAAPL1234C',
-//   panEntityType: 'Individual',
-//   registrationNumber: '1',
-//   checkDigit: 'E',
-// }
-
-parseGstin('not-a-gstin'); // { valid: false }
-```
-
-## What this validates
-
-A GSTIN is 15 characters: `SSPPPPPPPPPPPCZC`
-
-| Position | Meaning |
-|---|---|
-| 1-2 | State code |
-| 3-12 | Embedded PAN |
-| 13 | Registration number for this PAN within the state |
-| 14 | Reserved, always `Z` |
-| 15 | Checksum digit (mod-36) |
-
-This library checks, all offline:
-
-- **Format**: matches the 15-character structure above
-- **State code**: must be a real, currently-assigned GST state/UT code (not just any two digits)
-- **Checksum**: recomputes the mod-36 check digit and confirms it matches - this catches typos that a regex alone would miss
-- **Embedded PAN**: delegates to [`pan-card-validator`](https://www.npmjs.com/package/pan-card-validator) to confirm the embedded PAN has a valid structure and holder-category code
-
-Like PAN validation, this confirms a GSTIN is *well-formed and internally consistent* - it cannot confirm the GSTIN is *actually registered*. That requires the [GST Network's own verification API](https://www.gst.gov.in/).
-
-## License
-
-MIT
+# gst-validator
+
+## Module format
+
+This package is ESM-only. Use `import` syntax in Node.js projects with `type: module`. CommonJS applications can load it with `await import("gst-validator")`.
+
+
+Validate and parse Indian GSTIN numbers - real checksum verification, state-code lookup, and the embedded PAN, all offline.
+
+## Install
+
+```bash
+npm install gst-validator
+```
+
+## Usage
+
+```js
+import { isValidGstin, parseGstin } from 'gst-validator';
+
+isValidGstin('27AAAPL1234C1ZE'); // true
+isValidGstin('not-a-gstin');     // false
+
+parseGstin('27AAAPL1234C1ZE');
+// {
+//   valid: true,
+//   gstin: '27AAAPL1234C1ZE',
+//   stateCode: '27',
+//   stateName: 'Maharashtra',
+//   pan: 'AAAPL1234C',
+//   panEntityType: 'Individual',
+//   registrationNumber: '1',
+//   checkDigit: 'E',
+// }
+
+parseGstin('not-a-gstin'); // { valid: false }
+```
+
+## What this validates
+
+A GSTIN is 15 characters: `SSPPPPPPPPPPPCZC`
+
+| Position | Meaning |
+|---|---|
+| 1-2 | State code |
+| 3-12 | Embedded PAN |
+| 13 | Registration number for this PAN within the state |
+| 14 | Reserved, always `Z` |
+| 15 | Checksum digit (mod-36) |
+
+This library checks, all offline:
+
+- **Format**: matches the 15-character structure above
+- **State code**: must be a real, currently-assigned GST state/UT code (not just any two digits)
+- **Checksum**: recomputes the mod-36 check digit and confirms it matches - this catches typos that a regex alone would miss
+- **Embedded PAN**: delegates to [`pan-card-validator`](https://www.npmjs.com/package/pan-card-validator) to confirm the embedded PAN has a valid structure and holder-category code
+
+Like PAN validation, this confirms a GSTIN is *well-formed and internally consistent* - it cannot confirm the GSTIN is *actually registered*. That requires the [GST Network's own verification API](https://www.gst.gov.in/).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gst-validator",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Validate and parse Indian GSTIN numbers, including checksum verification and the embedded PAN",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,8 @@
     }
   },
   "files": [
-    "src"
+    "src",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.js"
@@ -33,7 +34,7 @@
   "bugs": {
     "url": "https://github.com/vjymisal0/gstin-validate/issues"
   },
-  "author": "",
+  "author": "Vijay Misal <misalvijay153@gmail.com>",
   "license": "MIT",
   "dependencies": {
     "pan-card-validator": "^1.0.0"
@@ -41,4 +42,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/src/gstin.js

@@ -1,129 +1,129 @@
-import { parsePan } from 'pan-card-validator';
-
-// Public spec: 2 state code + 10-char PAN + 1 entity number + 'Z' + 1 checksum.
-const GSTIN_PATTERN = /^([0-9]{2})([A-Z]{5}[0-9]{4}[A-Z])([1-9A-Z])(Z)([0-9A-Z])$/;
-const CHECKSUM_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
-
-// Published by the GST Network (as of 2026); code 97/99 reserved for
-// centralized/other jurisdictions not tied to a single state.
-const STATE_CODES = {
-  '01': 'Jammu and Kashmir',
-  '02': 'Himachal Pradesh',
-  '03': 'Punjab',
-  '04': 'Chandigarh',
-  '05': 'Uttarakhand',
-  '06': 'Haryana',
-  '07': 'Delhi',
-  '08': 'Rajasthan',
-  '09': 'Uttar Pradesh',
-  10: 'Bihar',
-  11: 'Sikkim',
-  12: 'Arunachal Pradesh',
-  13: 'Nagaland',
-  14: 'Manipur',
-  15: 'Mizoram',
-  16: 'Tripura',
-  17: 'Meghalaya',
-  18: 'Assam',
-  19: 'West Bengal',
-  20: 'Jharkhand',
-  21: 'Odisha',
-  22: 'Chattisgarh',
-  23: 'Madhya Pradesh',
-  24: 'Gujarat',
-  25: 'Daman and Diu',
-  26: 'Dadra and Nagar Haveli',
-  27: 'Maharashtra',
-  28: 'Andhra Pradesh',
-  29: 'Karnataka',
-  30: 'Goa',
-  31: 'Lakshadweep',
-  32: 'Kerala',
-  33: 'Tamil Nadu',
-  34: 'Puducherry',
-  35: 'Andaman and Nicobar Islands',
-  36: 'Telangana',
-  37: 'Andhra Pradesh (New)',
-  38: 'Ladakh',
-  97: 'Other Territory',
-};
-
-function normalize(input) {
-  return typeof input === 'string' ? input.trim().toUpperCase() : '';
-}
-
-function computeChecksum(gstinBody) {
-  let factor = 2;
-  let sum = 0;
-  const mod = CHECKSUM_CHARS.length;
-
-  for (let i = gstinBody.length - 1; i >= 0; i--) {
-    const codePoint = CHECKSUM_CHARS.indexOf(gstinBody[i]);
-    let digit = factor * codePoint;
-    digit = Math.floor(digit / mod) + (digit % mod);
-    sum += digit;
-    factor = factor === 2 ? 1 : 2;
-  }
-
-  const checksumIndex = (mod - (sum % mod)) % mod;
-  return CHECKSUM_CHARS[checksumIndex];
-}
-
-/**
- * Parses a GSTIN into its structural components, verifying its checksum
- * digit and the embedded PAN's structure.
- * @param {string} input
- * @returns {{
- *   valid: boolean,
- *   gstin?: string,
- *   stateCode?: string,
- *   stateName?: string,
- *   pan?: string,
- *   panEntityType?: string,
- *   registrationNumber?: string,
- *   checkDigit?: string,
- * }}
- */
-export function parseGstin(input) {
-  const gstin = normalize(input);
-  const match = GSTIN_PATTERN.exec(gstin);
-
-  if (!match) {
-    return { valid: false };
-  }
-
-  const [, stateCode, pan, registrationNumber, , checkDigit] = match;
-
-  if (!(stateCode in STATE_CODES)) {
-    return { valid: false };
-  }
-
-  if (computeChecksum(gstin.slice(0, 14)) !== checkDigit) {
-    return { valid: false };
-  }
-
-  const panInfo = parsePan(pan);
-  if (!panInfo.valid) {
-    return { valid: false };
-  }
-
-  return {
-    valid: true,
-    gstin,
-    stateCode,
-    stateName: STATE_CODES[stateCode] ?? null,
-    pan,
-    panEntityType: panInfo.entityType,
-    registrationNumber,
-    checkDigit,
-  };
-}
-
-/**
- * Validates a GSTIN's format, checksum, and embedded PAN structure.
- * @param {string} input
- * @returns {boolean}
- */
-export function isValidGstin(input) {
-  return parseGstin(input).valid;
-}
+import { parsePan } from 'pan-card-validator';
+
+// Public spec: 2 state code + 10-char PAN + 1 entity number + 'Z' + 1 checksum.
+const GSTIN_PATTERN = /^([0-9]{2})([A-Z]{5}[0-9]{4}[A-Z])([1-9A-Z])(Z)([0-9A-Z])$/;
+const CHECKSUM_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+// Published by the GST Network (as of 2026); code 97/99 reserved for
+// centralized/other jurisdictions not tied to a single state.
+const STATE_CODES = {
+  '01': 'Jammu and Kashmir',
+  '02': 'Himachal Pradesh',
+  '03': 'Punjab',
+  '04': 'Chandigarh',
+  '05': 'Uttarakhand',
+  '06': 'Haryana',
+  '07': 'Delhi',
+  '08': 'Rajasthan',
+  '09': 'Uttar Pradesh',
+  10: 'Bihar',
+  11: 'Sikkim',
+  12: 'Arunachal Pradesh',
+  13: 'Nagaland',
+  14: 'Manipur',
+  15: 'Mizoram',
+  16: 'Tripura',
+  17: 'Meghalaya',
+  18: 'Assam',
+  19: 'West Bengal',
+  20: 'Jharkhand',
+  21: 'Odisha',
+  22: 'Chattisgarh',
+  23: 'Madhya Pradesh',
+  24: 'Gujarat',
+  25: 'Daman and Diu',
+  26: 'Dadra and Nagar Haveli',
+  27: 'Maharashtra',
+  28: 'Andhra Pradesh',
+  29: 'Karnataka',
+  30: 'Goa',
+  31: 'Lakshadweep',
+  32: 'Kerala',
+  33: 'Tamil Nadu',
+  34: 'Puducherry',
+  35: 'Andaman and Nicobar Islands',
+  36: 'Telangana',
+  37: 'Andhra Pradesh (New)',
+  38: 'Ladakh',
+  97: 'Other Territory',
+};
+
+function normalize(input) {
+  return typeof input === 'string' ? input.trim().toUpperCase() : '';
+}
+
+function computeChecksum(gstinBody) {
+  let factor = 2;
+  let sum = 0;
+  const mod = CHECKSUM_CHARS.length;
+
+  for (let i = gstinBody.length - 1; i >= 0; i--) {
+    const codePoint = CHECKSUM_CHARS.indexOf(gstinBody[i]);
+    let digit = factor * codePoint;
+    digit = Math.floor(digit / mod) + (digit % mod);
+    sum += digit;
+    factor = factor === 2 ? 1 : 2;
+  }
+
+  const checksumIndex = (mod - (sum % mod)) % mod;
+  return CHECKSUM_CHARS[checksumIndex];
+}
+
+/**
+ * Parses a GSTIN into its structural components, verifying its checksum
+ * digit and the embedded PAN's structure.
+ * @param {string} input
+ * @returns {{
+ *   valid: boolean,
+ *   gstin?: string,
+ *   stateCode?: string,
+ *   stateName?: string,
+ *   pan?: string,
+ *   panEntityType?: string,
+ *   registrationNumber?: string,
+ *   checkDigit?: string,
+ * }}
+ */
+export function parseGstin(input) {
+  const gstin = normalize(input);
+  const match = GSTIN_PATTERN.exec(gstin);
+
+  if (!match) {
+    return { valid: false };
+  }
+
+  const [, stateCode, pan, registrationNumber, , checkDigit] = match;
+
+  if (!(stateCode in STATE_CODES)) {
+    return { valid: false };
+  }
+
+  if (computeChecksum(gstin.slice(0, 14)) !== checkDigit) {
+    return { valid: false };
+  }
+
+  const panInfo = parsePan(pan);
+  if (!panInfo.valid) {
+    return { valid: false };
+  }
+
+  return {
+    valid: true,
+    gstin,
+    stateCode,
+    stateName: STATE_CODES[stateCode] ?? null,
+    pan,
+    panEntityType: panInfo.entityType,
+    registrationNumber,
+    checkDigit,
+  };
+}
+
+/**
+ * Validates a GSTIN's format, checksum, and embedded PAN structure.
+ * @param {string} input
+ * @returns {boolean}
+ */
+export function isValidGstin(input) {
+  return parseGstin(input).valid;
+}

package/src/index.d.ts

@@ -1,21 +1,21 @@
-export interface ParsedGstin {
-  valid: boolean;
-  gstin?: string;
-  stateCode?: string;
-  stateName?: string | null;
-  pan?: string;
-  panEntityType?: string;
-  registrationNumber?: string;
-  checkDigit?: string;
-}
-
-/**
- * Parses a GSTIN into its structural components, verifying its checksum
- * digit and the embedded PAN's structure.
- */
-export function parseGstin(input: string): ParsedGstin;
-
-/**
- * Validates a GSTIN's format, checksum, and embedded PAN structure.
- */
-export function isValidGstin(input: string): boolean;
+export interface ParsedGstin {
+  valid: boolean;
+  gstin?: string;
+  stateCode?: string;
+  stateName?: string | null;
+  pan?: string;
+  panEntityType?: string;
+  registrationNumber?: string;
+  checkDigit?: string;
+}
+
+/**
+ * Parses a GSTIN into its structural components, verifying its checksum
+ * digit and the embedded PAN's structure.
+ */
+export function parseGstin(input: string): ParsedGstin;
+
+/**
+ * Validates a GSTIN's format, checksum, and embedded PAN structure.
+ */
+export function isValidGstin(input: string): boolean;

package/src/index.js

@@ -1 +1 @@
-export { isValidGstin, parseGstin } from './gstin.js';
+export { isValidGstin, parseGstin } from './gstin.js';