gst-validator 1.0.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,57 @@
+# 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

@@ -0,0 +1,44 @@
+{
+  "name": "gst-validator",
+  "version": "1.0.0",
+  "description": "Validate and parse Indian GSTIN numbers, including checksum verification and the embedded PAN",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "gstin",
+    "gst",
+    "india",
+    "validator",
+    "kyc",
+    "tax-id"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vjymisal0/gstin-validate.git"
+  },
+  "homepage": "https://github.com/vjymisal0/gstin-validate#readme",
+  "bugs": {
+    "url": "https://github.com/vjymisal0/gstin-validate/issues"
+  },
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "pan-card-validator": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/gstin.js

@@ -0,0 +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;
+}

package/src/index.d.ts

@@ -0,0 +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;

package/src/index.js

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